Model storage

Every Modaic Model lives in a private Git 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 storage is optimized for fast checkpoint loading, so you can use versioned checkpoints directly in production inference.

Model identity

A Model has two identifiers:

Repository path — workspace/slug, such as acme/support-priority. Use this path in POST /v1/systemone.
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-fast",
  "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
  }
}

Field	Meaning
`schemaVersion`	Configuration format. Currently `1`.
`model`	Root model used to make decisions.
`checkpoint`	Monotonic version of aligned instructions. New Models start at `0`.
`questions`	Named `noul`, `choice`, or `score` decision tasks.
`metrics`	Optional accuracy and calibration measurements for the current checkpoint.
`capture.sampleRate`	Fraction of live repository-model decisions to record, from 0 to 1.

Revisions

Each Model revision is a Git commit. 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.

Keeping and restoring versions

Tag what you want to keep. After an alignment completes, tag its resultCommitSha (v1, aligned-2026-09-24) and pass the tag as revision on decisions. Production then stays on that version no matter what happens to the branch.
Update with the head you read. Send the commit.commitSha from a model read back as expectedHeadSha on an update. A stale client is refused with 409 expected_head_mismatch instead of overwriting newer commits.
Aligned questions are protected. An update whose questions differ from an aligned checkpoint is refused with 409 alignment_would_be_discarded unless discardAlignment: true is sent.
Roll back, don't reconstruct. If a version was overwritten anyway, list the commits and roll the branch back to the one you want. The rollback is a new commit with the target's files, so the checkpoint and metrics return intact.

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.