# systemone.yaml

> The manifest specification — the decision-native metadata that makes models on the registry comparable.

Source: https://dev.systemonemodels.tech/docs/manifest

## Why a manifest

Storage does not make a model adoptable. Finding the right one does, and that
needs metadata a machine can filter on: what the model decides, how well
calibrated it is, how fast it responds, what it was built from.

`systemone.yaml` is deliberately small enough that authors write it by hand, and
closed where being closed is the point.

## A complete example

```yaml
spec_version: "0.1"
model: support-router
namespace: biplov
category: system-one
architecture: laya
base_model: acme/laya-base
license: apache-2.0
summary: Routes inbound support tickets to the right queue.

capabilities:
  - choice
  - route

tags:
  - routing
  - support

runtime:
  framework: pytorch
  entrypoint: support_router:load
  python: ">=3.10"
  hardware: cpu

artifacts:
  - kind: huggingface
    uri: https://huggingface.co/biplov/support-router/resolve/main/model.safetensors
    filename: model.safetensors
    sha256: 0000000000000000000000000000000000000000000000000000000000000000

evaluation:
  suite: s1-decision-bench
  suite_version: "0.1"
  decision_accuracy: 0.943
  calibration_error: 0.031
  valid_action_rate: 0.999
  median_latency_ms: 4.7
  p95_latency_ms: 9.1
```

## Fields

| Field | Required | Notes |
| --- | --- | --- |
| `spec_version` | yes | Currently `"0.1"`. An unknown version is rejected rather than guessed at. |
| `model` | yes | Repository name. Lowercase, 2–64 characters. |
| `namespace` | yes | Your username or an organization you own. |
| `category` | yes | Always `system-one`. |
| `architecture` | yes | `laya`, `jev`, or another identifier. Free text until the field set is proven. |
| `capabilities` | yes | One or more of `choice`, `score`, `rank`, `classify`, `extract`, `route`. |
| `runtime` | yes | `framework` required; `entrypoint`, `python`, `hardware` optional. |
| `license` | no | A curated SPDX subset, or `other` with `license_name`. |
| `base_model` | no | `namespace/name` this was fine-tuned from. |
| `summary` | no | One line, at most 280 characters. |
| `tags` | no | Up to 20, lowercase. |
| `artifacts` | no | Where the files live. Never uploads. |
| `evaluation` | no | Strongly recommended. See below. |

Unknown fields are **rejected**, not ignored — a typo should fail loudly rather
than silently drop the value you meant to set.

## Capabilities are closed

`capabilities` is an enum, not free text. This is the field that makes the
registry filterable, and a field that accepts anything is a field nobody can
filter on. Six values cover the decision primitives:

- `choice` — pick one option from a candidate set
- `route` — choice, where the options are destinations
- `classify` — assign a category from a fixed taxonomy
- `score` — return a number on a continuum
- `rank` — order a set of items
- `extract` — pull typed values out of an input

## Evaluation is what earns trust

Accuracy alone does not describe a decision model.

- `decision_accuracy` — how often it is right.
- `calibration_error` — whether its confidence means anything. A model that
  reports 0.95 on cases it gets right 70% of the time makes every threshold you
  set from it wrong.
- `valid_action_rate` — how often it picks an option that actually exists.
- `median_latency_ms` / `p95_latency_ms` — whether it can sit in a request path.

Publishing calibration beside accuracy is the single thing that makes your model
easier to adopt than an otherwise identical one.

## Validating

The API validates and returns **every** problem at once, rather than one per
attempt:

```bash
curl -X POST https://api.systemonemodels.tech/v1/manifest/validate \
  -H 'content-type: text/plain' \
  --data-binary @systemone.yaml
```

```json
{
  "valid": false,
  "issues": [
    { "path": "license", "message": "unknown license 'apache2'", "kind": "schema" },
    { "path": "capabilities", "message": "List should have at least 1 item", "kind": "schema" }
  ]
}
```

The machine-readable schema is at
[`/v1/manifest/spec`](https://api.systemonemodels.tech/v1/manifest/spec).