Skip to content

CLI

The system-one console script. system-one-mcp stays as an alias for system-one mcp.

system-one fetch  [--variant fp32|int8|fp16] [-o onnx] [--revision main]
system-one export <spec.yaml|spec.json> [-o onnx]
system-one mcp    [--config questions.yaml] [--generic] [--transport stdio]

fetch needs pip install "system-one[hub]", export needs pip install "system-one[export]" (torch); mcp needs system-one[mcp].

Both fetch and export write a source block into <name>.json recording the repo, the resolved revision, the weights digest and the graph digest; the backend checks graph_sha256 when it loads the graph. See Source.

ExportSpec

Bases: BaseModel

One export: where the checkpoint comes from and how to build it.

Source code in system_one/catalog.py 
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
class ExportSpec(BaseModel):
    """One export: where the checkpoint comes from and how to build it."""

    model_config = ConfigDict(frozen=True, extra="forbid")

    name: str
    repo: str | None = None
    revision: str | None = None
    subfolder: str = ""
    path: Path | None = None
    builder: str = "system_one.export:build_decision_model"
    config_file: str = CONFIG_FILE
    weights: str = "model.safetensors"
    tokenizer_dir: str = "tokenizer"
    patterns: list[str] = Field(default_factory=_default_patterns)
    calibration: tuple[str, ...] = CALIBRATION_KEYS
    opset: int = 18

    @model_validator(mode="after")
    def _check_source(self) -> ExportSpec:
        if (self.repo is None) == (self.path is None):
            raise ValueError("set exactly one of 'repo' or 'path'")
        return self

name instance-attribute 

name: str

repo class-attribute instance-attribute 

repo: str | None = None

revision class-attribute instance-attribute 

revision: str | None = None

subfolder class-attribute instance-attribute 

subfolder: str = ''

path class-attribute instance-attribute 

path: Path | None = None

builder class-attribute instance-attribute 

builder: str = 'system_one.export:build_decision_model'

config_file class-attribute instance-attribute 

config_file: str = CONFIG_FILE

weights class-attribute instance-attribute 

weights: str = 'model.safetensors'

tokenizer_dir class-attribute instance-attribute 

tokenizer_dir: str = 'tokenizer'

patterns class-attribute instance-attribute 

patterns: list[str] = Field(
    default_factory=_default_patterns
)

calibration class-attribute instance-attribute 

calibration: tuple[str, ...] = CALIBRATION_KEYS

opset class-attribute instance-attribute 

opset: int = 18

Source

Bases: BaseModel

The optional source block of <name>.json: what produced the graph beside it.

Only graph_sha256 is checked at load time; the rest answers "which weights produced this number" after the fact. Fields left None are dropped on write — weights_sha256 for a downloaded graph, variant for an export.

Source code in system_one/catalog.py 
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
class Source(BaseModel):
    """The optional `source` block of `<name>.json`: what produced the graph beside it.

    Only `graph_sha256` is checked at load time; the rest answers "which weights
    produced this number" after the fact. Fields left `None` are dropped on write —
    `weights_sha256` for a downloaded graph, `variant` for an export.
    """

    model_config = ConfigDict(frozen=True, extra="forbid")

    repo: str
    revision: str
    graph_sha256: str
    exporter: str = EXPORTER
    subfolder: str = ""
    weights_sha256: str | None = None
    opset: int | None = None
    variant: str | None = None
    calibration: str | None = None

repo instance-attribute 

repo: str

revision instance-attribute 

revision: str

graph_sha256 instance-attribute 

graph_sha256: str

exporter class-attribute instance-attribute 

exporter: str = EXPORTER

subfolder class-attribute instance-attribute 

subfolder: str = ''

weights_sha256 class-attribute instance-attribute 

weights_sha256: str | None = None

opset class-attribute instance-attribute 

opset: int | None = None

variant class-attribute instance-attribute 

variant: str | None = None

calibration class-attribute instance-attribute 

calibration: str | None = None

source_block 

source_block(graph: Path, **fields: Any) -> dict[str, Any]

A Source for graph as plain JSON, ready to merge into the calibration.

Source code in system_one/catalog.py 
84
85
86
87
def source_block(graph: Path, **fields: Any) -> dict[str, Any]:
    """A `Source` for `graph` as plain JSON, ready to merge into the calibration."""
    source = Source(graph_sha256=sha256_file(graph), **fields)
    return source.model_dump(exclude_none=True)

load_spec 

load_spec(path: Path) -> ExportSpec

Read and validate an export spec; YAML is a JSON superset, so one loader does.

Source code in system_one/catalog.py 
128
129
130
131
132
133
134
135
def load_spec(path: Path) -> ExportSpec:
    """Read and validate an export spec; YAML is a JSON superset, so one loader does."""
    text = path.read_text()
    try:
        import yaml
    except ImportError:
        return ExportSpec.model_validate(json.loads(text))
    return ExportSpec.model_validate(yaml.safe_load(text))

fetch_plan 

fetch_plan(
    variant: str, name: str = DEFAULT_NAME
) -> list[tuple[str, str]]

Remote-to-local file mapping for fetch, kept pure so it is testable offline.

Source code in system_one/catalog.py 
138
139
140
141
142
143
144
145
def fetch_plan(variant: str, name: str = DEFAULT_NAME) -> list[tuple[str, str]]:
    """Remote-to-local file mapping for `fetch`, kept pure so it is testable offline."""
    plan = [
        (remote, f"{name}.onnx.data" if remote.endswith(".data") else f"{name}.onnx")
        for remote in FETCH_VARIANTS[variant]
    ]
    plan.append(("tokenizer.json", "tokenizer/tokenizer.json"))
    return plan

fetch 

fetch(
    out_dir: Path,
    variant: str = "fp32",
    revision: str = "main",
    name: str = DEFAULT_NAME,
) -> None

Download the published reference graph into the layout load_model reads.

Source code in system_one/cli.py 
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
def fetch(
    out_dir: Path,
    variant: str = "fp32",
    revision: str = "main",
    name: str = DEFAULT_NAME,
) -> None:
    """Download the published reference graph into the layout `load_model` reads."""
    try:
        from huggingface_hub import hf_hub_download
    except ImportError as exc:
        raise ImportError(EXTRA_HINTS["fetch"]) from exc

    resolved = revision
    for remote, local in fetch_plan(variant, name):
        target = out_dir / local
        target.parent.mkdir(parents=True, exist_ok=True)
        source = Path(
            hf_hub_download(FETCH_REPO, remote, revision=revision)  # nosec B615
        )
        shutil.copyfile(source, target)
        if "snapshots" in source.parts:
            resolved = source.parts[source.parts.index("snapshots") + 1]
        print(f"{remote} -> {target}")

    calibration = out_dir / f"{name}.json"
    calibration.write_text(
        json.dumps(
            {
                **FETCH_CALIBRATION,
                "source": source_block(
                    out_dir / f"{name}.onnx",
                    repo=FETCH_REPO,
                    revision=resolved,
                    variant=variant,
                    calibration="system_one.catalog:FETCH_CALIBRATION",
                ),
            },
            indent=1,
        )
    )
    print(f"wrote {calibration}")

Exporter

The export subcommand loads system_one.export, which imports torch.

build_decision_model 

build_decision_model(
    config: dict[str, Any], model_dir: Path
) -> Module

Default builder: an encoder from transformers under the decision head above.

Source code in system_one/export.py 
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
def build_decision_model(config: dict[str, Any], model_dir: Path) -> torch.nn.Module:
    """Default builder: an encoder from `transformers` under the decision head above."""
    from transformers import AutoConfig, AutoModel

    loader = cast("Any", AutoModel)
    encoder_dir = model_dir / "encoder"
    if encoder_dir.exists():
        encoder_config = AutoConfig.from_pretrained(str(encoder_dir))  # nosec B615
        encoder = loader.from_config(encoder_config, attn_implementation="sdpa")
    else:
        encoder = loader.from_pretrained(  # nosec B615
            config["encoder"], attn_implementation="sdpa"
        )
    encoder.config.reference_compile = False
    return DecisionModel(
        encoder, config.get("head_layers", 2), len(config.get("act_costs", {})) + 1
    )

run_export 

run_export(spec: ExportSpec, out_dir: Path) -> None

Export spec into <out_dir>/<name>.onnx, <name>.json and tokenizer/.

Source code in system_one/export.py 
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
def run_export(spec: ExportSpec, out_dir: Path) -> None:
    """Export `spec` into `<out_dir>/<name>.onnx`, `<name>.json` and `tokenizer/`."""
    model_dir, revision = resolve_source(spec)
    graph, config = load_graph(spec, model_dir)
    out_dir.mkdir(parents=True, exist_ok=True)

    target = out_dir / f"{spec.name}.onnx"
    example = sample_inputs()
    export(graph, example, target, spec.opset)

    shutil.copytree(
        model_dir / spec.tokenizer_dir, out_dir / "tokenizer", dirs_exist_ok=True
    )
    calibration = {key: config[key] for key in spec.calibration}
    calibration["source"] = source_block(
        target,
        repo=spec.repo or str(spec.path),
        revision=revision,
        subfolder=spec.subfolder,
        weights_sha256=sha256_file(model_dir / spec.weights),
        opset=spec.opset,
    )
    (out_dir / f"{spec.name}.json").write_text(json.dumps(calibration, indent=1))

    report_parity(graph, example, target)
    written = sum(f.stat().st_size for f in out_dir.glob(f"{spec.name}.onnx*"))
    print(f"wrote {target} ({written / 1e6:.0f} MB)")