Preparing Models with modelctl

The Xisom runtime executes models in ONNX format. modelctl is a command-line tool you run on a developer workstation — not on the box — to turn a trained PyTorch or TensorFlow model into a validated, optionally quantized, checksummed ONNX bundle you can carry onto an air-gapped edge device.

It complements the offline bundle install: that flow installs the product; modelctl produces the per-model artifacts you deploy afterwards.

The workflow

flowchart LR
  subgraph WS["Developer workstation — modelctl"]
    direction LR
    SRC["Trained model<br/>PyTorch .pt / TF SavedModel"] --> CV["convert<br/>→ ONNX"]
    CV --> VL["validate<br/>schema · opset · runtime · inference"]
    VL --> QZ["quantize<br/>dynamic INT8 (optional)"]
    QZ --> PK["package<br/>checksummed bundle"]
  end
  PK -->|"copy bundle (USB / offline)"| BOX["Edge box<br/>upload + activate"]

Install

modelctl requires Python 3.11+. The heavy ML frameworks are optional — the core install runs validate, quantize, and package with no PyTorch or TensorFlow. You only need the extras to convert from those frameworks.

pip install modelctl

convert from PyTorch or TensorFlow is unavailable until you add an extra below.

pip install 'modelctl[pytorch]'

pip install 'modelctl[tensorflow]'

pip install 'modelctl[all]'

pip install 'modelctl[quantize]'

Needed for quantize and package --quantize (pulls ml_dtypes).

Convert → validate → package

Convert to ONNX
Section titled “Convert to ONNX”

PyTorch input is a TorchScript .pt (torch.jit.save) — self-contained, so the convert box needs no model class. TensorFlow input is a SavedModel directory.
Terminal window
modelctl convert --source model.pt --format pytorch --output model.onnx \ --input-shape 1,3,224,224 --opset 18
Terminal window
modelctl convert --source saved_model/ --format tensorflow --output model.onnx
Terminal window
modelctl convert --config model.yaml
CLI flags override YAML, which overrides defaults.
Validate against the edge runtime
Section titled “Validate against the edge runtime”

Validation checks ONNX schema, opset vs. the edge ONNX Runtime, the edge input contract (single input · float32 · rank), runtime load, and a test inference. Pin the device’s ORT version so a too-new model is caught before it reaches an air-gapped box.
Terminal window
```
modelctl validate --model model.onnx --target-ort 1.18
# ✓ ONNX schema valid
# ✓ Opset supported
# ✓ Single input tensor
# ✓ Input dtype float32
# ✓ Input rank
# ✓ ONNX Runtime load successful
# ✓ Test inference successful
```

Package into a bundle

modelctl package --model model.onnx --name pump-anomaly-v1

This emits a portable directory:

pump-anomaly-v1/
├── model.onnx
├── metadata.json        # name, version, framework, opset, quantized flag
├── input_schema.json    # input tensor name / shape / dtype
├── checksums.sha256     # SHA256 over the model + metadata + schema
└── README.md

Copy the directory to the box, then verify integrity on the device:

cd pump-anomaly-v1 && sha256sum -c checksums.sha256

Tuning for edge performance

modelctl has two levers that affect how the model runs on the box:

Dynamic INT8 quantization — modelctl quantize --model model.onnx --output model.int8.onnx (or --quantize on convert/package) produces a smaller model that is typically faster to load and run, at some accuracy cost. Requires the [quantize] extra. Validate the quantized model and confirm prediction quality before shipping it.
Opset targeting — --target-ort validates the model’s opset against the exact ONNX Runtime on the device, so an export that is too new fails on the workstation instead of on the floor.

Next steps

modelctl Best Practices Do/don't guidance: profiles, validation gating, reproducible bundles, CI.

Deploy the model Upload the ONNX, pair it with a datasource, activate.

Offline bundle install Get the product onto an air-gapped box.