Modaicmodaic % docs

Search Modaic documentation

Find a Modaic guide or API reference

Model repositories

Every Modaic Model lives in a private repository. The repository is the Model's versioned source of truth: it records the root model, typed questions, checkpoints, metrics, capture policy, and alignment artifacts.

Model identity

A Model has two identifiers:

  • Repository path — owner/slug, such as acme/support-triage. Use this path in POST /v1/decision.
  • Model ID — a UUID returned when the repository is created. Use it in resource routes for examples, metrics, batch decisions, and alignments.

Repository paths are human-readable. Model IDs remain stable if display metadata changes.

The model configuration

The root model.json file contains the decision contract for a revision.

{
  "schemaVersion": 1,
  "model": "mo",
  "checkpoint": 0,
  "questions": {
    "priority": {
      "type": "choice",
      "instructions": "Choose the support priority.",
      "criteria": {
        "low": "No time-sensitive impact.",
        "normal": "Routine customer issue.",
        "high": "Financial impact or an urgent blocker."
      }
    }
  },
  "capture": {
    "sampleRate": 1
  }
}
FieldMeaning
schemaVersionConfiguration format. Currently 1.
modelRoot model used to make decisions.
checkpointMonotonic version of aligned instructions. New Models start at 0.
questionsNamed noul, choice, or score decision tasks.
metricsOptional accuracy and calibration measurements for the current checkpoint.
capture.sampleRateFraction of live repository-model decisions to record, from 0 to 1.

Revisions

Branches support ongoing work, tags can name releases, and commit SHAs pin an immutable Model revision. Pass revision to the Decision API when you need reproducible behavior; otherwise Modaic resolves the repository's default branch.

Batch decisions record their exact sourceCommitSha. Alignments also require the current source commit and will refuse to update a branch that has advanced. This keeps evaluation and optimization attached to the Model version they actually used.

Access roles

Repository access has three roles:

  • Reader — view the Model, examples, decisions, metrics, and jobs.
  • Writer — update configuration, annotate examples, and start or cancel batch decisions and alignments.
  • Admin — change repository metadata and permanently delete the Model.

Private resources return 404 to callers who cannot access them.

Was this page helpful?