Models with the SDK

Models hold a versioned decision configuration and the examples, decisions, and jobs associated with it.

List models

import { Modaic } from "modaic";

const modaic = new Modaic();
const available = await modaic.models.list();

for (const model of available.models) {
  console.log(model.name, model.type, model.repositoryId);
}

The response includes Modaic base models and repository models the API key can access.

Create and configure a model

const model = await modaic.models.create({
  workspace: "acme",
  slug: "support-priority",
  description: "Prioritizes support tickets and identifies refund requests.",
  model: "mo-fast",
  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.",
      },
    },
  },
});

console.log(model.id);

The initial criteria are saved when the model is created. With questions supplied, model defaults to mo-fast if omitted.

Update a model

const configured = await modaic.models.update(model.id, {
  questions: {
    priority: {
      type: "choice",
      criteria: {
        normal: "Routine customer issue.",
        high: "Financial impact or an urgent blocker.",
      },
    },
  },
  message: "Simplify priority levels",
});
console.log(configured.commit?.commitSha);

Configuration updates create immutable commits. Pass branch to update a branch other than the default.

Alignment stores its optimized instructions in the same questions you set here. Once a model has an alignment checkpoint, an update whose questions differ from the stored ones fails with 409 alignment_would_be_discarded instead of silently reverting the model. Leave questions out to keep the aligned instructions, or pass discardAlignment: true (TypeScript) / discard_alignment=True (Python) to replace them and reset the checkpoint.

Branches, tags, and rollback

Every model is a Git repository, and the SDK exposes its history. models.get returns commit, the default branch's head, so you can update safely and tag what you want to keep.

const model = await modaic.models.get("acme", "support-priority");

// Refuse to overwrite anything newer than what we read. The check applies to
// configuration changes (`model` or `questions`), not description-only updates.
const updated = await modaic.models.update(model.id, {
  questions: {
    priority: {
      type: "choice",
      instructions: "Choose the support priority for this ticket.",
      criteria: {
        normal: "Routine customer issue.",
        high: "Financial impact or an urgent blocker.",
      },
    },
  },
  expectedHeadSha: model.commit!.commitSha,
});

// Name the new commit and pin production to it.
await modaic.models.createTag(model.id, { name: "v1", commitSha: updated.commit!.commitSha });
await modaic.decisions.create({ model: "acme/support-priority", revision: "v1", state: { ticket: "..." } });

// Undo a bad update: move main back to an earlier commit.
const { commits } = await modaic.models.listCommits(model.id, { branch: "main" });
await modaic.models.rollback(model.id, {
  branch: "main",
  targetCommitSha: commits[1]!.sha,
  expectedHeadSha: commits[0]!.sha,
  message: "Restore checkpoint 1",
});

A rollback is a new commit with the target's files, so model.json returns with its checkpoint and metrics. listBranches / list_branches, createBranch / create_branch, deleteBranch / delete_branch, listTags / list_tags, and deleteTag / delete_tag complete the set.

Get and delete a model

const model = await modaic.models.get("acme", "support-priority");
console.log(model.id, model.defaultBranch, model.configuration);

await modaic.models.delete(model.id);

Model deletion is permanent and removes the model's examples, decisions, and job history. Use the model ID returned by create() or get().

Was this page helpful?