---
name: systemone-models
description: Package, check and publish System One decision models on systemonemodels.tech. Covers the systemonemodels CLI and SDK (login, push, pull, systemone.yaml), OpenDXP packages (export, conformance, validate, check, serve), the live playground and the badges. Use when the user wants to publish, fine-tune, package, run or serve a System One model, or make one OpenDXP compatible.
---

# System One Models: package, check and publish a decision model

A **System One model** answers typed questions about a state (`choice`: pick an option;
`score`: place it on an ordered scale; `noul`: yes or no) with a calibrated probability
for every option, in one forward pass, without generating text. **System One Models**
(https://systemonemodels.tech) is the registry and developer platform for them. **OpenDXP** is the open
standard (Apache-2.0) that makes a model a package any engine runs without the model's own
code. Full documentation, as Markdown: https://systemonemodels.tech/llms.txt

## Before you start

- Ask the user which model (a folder with its weights, or a Hugging Face repository),
  which namespace to publish under (their username or an organization), and its licence.
- Never publish weights whose licence forbids redistribution. Never invent evaluation
  numbers: report only what a run produced.
- Publishing needs an account with a verified email.

## 1. Install and sign in

```bash
pip install systemonemodels          # the systemone CLI and Python SDK
systemone login                      # browser sign-in; --no-browser over SSH, --token TEXT in CI
systemone whoami
```

## 2. Publish the model as it is

```bash
systemone push ./my-model --repo NAMESPACE/NAME --dry-run   # always look first
systemone push ./my-model --repo NAMESPACE/NAME
```

`push` finds the weights (`model.safetensors`, `model.onnx`, a `.gguf`, a `.mlpackage`),
writes `systemone.yaml` (the manifest), the model card and the evaluation from the files,
and uploads only files the registry does not already hold. Versions are immutable. Use
`--namespace ORG` for an organization, `--version`, `--private`, `--manifest PATH` to use
your own manifest, and `systemone validate systemone.yaml` to check one first. No pickles,
and no configs that make a loader import code. Manifest reference:
https://systemonemodels.tech/docs/manifest.md

## 3. Make it OpenDXP compatible

Read https://systemonemodels.tech/docs/opendxp-compatible.md first; it is the full procedure. In short:

```bash
pip install "opendxp[onnx]"          # encoder-markers; "opendxp[gguf]" for causal-letters
```

1. **Profile.** A bidirectional encoder scoring one marker token per option (Laya, Julia 1)
   is `encoder-markers` (ONNX + `template.json`). A language model reading each option
   letter's probability at an answer slot (Decider) is `causal-letters` (GGUF +
   `prompt.json`). An instruction-tuned model asked in its chat template, option by option
   in rotation (AnyJev), is `causal-letters` with typed layouts (OpenDXP 0.2).
2. **Converters.** For these families one command writes the package:
   `opendxp export laya|julia|decider|anyjev CHECKPOINT odxp/`. For any other model, write
   the package by hand: export the weights (ONNX with the standard signature, or the GGUF
   unchanged; convert safetensors at their own precision, F16 for BF16), then describe the
   input as data in `template.json` or `prompt.json`. Nothing in a package may be code.
3. **Prove it matches the model's own code.** Test the declarative input against the model's
   own prompt builder on a few hundred random requests: the token ids must be identical.
4. **Calibration.** `calibration.json`: the temperature the model's code applies, per
   question type (and optionally per option count).
5. **Conformance.** Write a native adapter (a function that answers a System One request
   with the model's own package, on the CPU), then record its answers:
   `opendxp conformance generate odxp/ --native CHECKPOINT --runtime NAME`.
6. **Check.**
   ```bash
   opendxp validate odxp/            # schemas, parsers, coverage, hashes
   opendxp check odxp/               # replays conformance.jsonl through the reference runtime
   ```
   It passes when every question gets the same decision and every probability is within
   0.01 of the model's own code. If it fails, look at tokenization at piece boundaries,
   the llama.cpp settings (`decode`: flash attention, an f32 cache), an undeclared
   temperature clamp, or quantized weights (a derived package: check it, do not expect it
   to pass). Never call a model OpenDXP compatible unless `opendxp check` passed.
7. **Publish.** Put the package in an `odxp/` folder next to the model and push the version
   (step 2). The registry's engine finds it by its `odxp.json`.

Specification: https://github.com/systemonemodels/opendxp/blob/main/SPEC.md

## 4. Run and serve it anywhere

```bash
systemone run opendxp NAMESPACE/NAME --state "Customer: where is my parcel?" \
    --questions '{"intent": {"type": "choice", "instructions": "What does the customer want?", "criteria": ["refund", "track delivery", "cancel order"]}}'
opendxp run odxp/ --request request.json
opendxp serve odxp/                  # HTTP: POST /v1/systemone, GET /v1/models on 127.0.0.1:8790
opendxp mcp odxp/                    # a tool for AI agents over the Model Context Protocol
```

A request is `{"state": "...", "questions": {"id": {"type": "choice" | "score" | "noul",
"instructions": "...", "criteria": ...}}}`: choice criteria are `{name: description or null}`
or a list of names; score criteria a list of level descriptions, lowest first; noul criteria
absent or `{"false": ..., "true": ...}`. Answers carry a probability per option (noul: the
probability of true).

## 5. On systemonemodels.tech

- **Live playground.** On the model's page, Playground tab, "Request a live playground". An
  admin approves it and the engine loads the model (CPU today: models up to about 2.5B
  parameters).
- **OpenDXP compatible** appears on the model's page, and on the profile of the user or
  organization that published it, once the engine's check of its package passes. The engine
  checks published packages up to 2.5 GB by itself. It is the only OpenDXP badge, and it is
  earned only by publishing a model that passes.
- **Inference API.** A model with a live playground can be called from code with an API key
  (https://systemonemodels.tech/settings/api): `Client(api_key).decide(model, state, questions)` from
  `systemone` (systemonemodels 0.4 or later), or `POST /v1/systemone` on
  https://api.systemonemodels.tech. Reference: https://systemonemodels.tech/docs/inference.md
- **Fine-tuning.** `systemone run studio` opens System One Studio locally, which fine-tunes
  Laya and publishes the result in one click.

Help: ceo@systemonemodels.tech