The three files#
A deployment is three JSON documents with three lifetimes: the model file travels with the
model, the contract file names the run, the context file lives on the machine. Each is read
by a static loader of its handle; the model and context configs are written back by to_json().
try {
anira::ModelConfig model = anira::ModelConfig::from_file("model.model.json");
anira::ContractHandle contract = anira::ContractHandle::from_file("model.contract.json");
anira::ContextConfig context = anira::ContextConfig::from_file("context.json");
// from_json(text) for each; ModelConfig::from_json(text, base_dir) resolves relative paths
} catch (const anira::Error& e) {
std::fprintf(stderr, "%s\n", e.what()); // ANIRA_ERROR_JSON: "models[0].engine: ..."
}
The loaders only translate (words to enums, numbers to numbers); every semantic check happens at
prepare, the same way for a file and for code, so a document that loads may still be refused there.
A failure is ANIRA_ERROR_JSON with the key path and the offending value
(models[0].engine: "foo" is not one of ...), or ANIRA_ERROR_NO_SUCH_FILE. A key the loader
does not own is stored as an extension and fails prepare by name, so a typo never becomes a default.
The model file#
{
"models": [
{ "engine": "onnxruntime", "path": "model.onnx",
"tensors": { "audio_in": "input.1", "mask_out": "output" } },
{ "engine": "libtorch", "path": "model.pt", "entry": { "name": "forward_streaming" } },
{ "engine": "executorch", "provider": "xnnpack", "path": "model_xnnpack.pte" }
],
"default_engine": "onnxruntime",
"default_provider": "cuda",
"state": "stateless",
"max_instances": 4,
"inputs": [
{ "name": "audio_in", "dtype": "float32", "role": "streamed",
"axes": [ ["batch", 1], ["channel", 2], ["time", "dynamic"] ],
"window": { "min": 2048, "max": 8192 }, "overlap": 1024 }
],
"outputs": [
{ "name": "mask_out", "role": "streamed",
"axes": [ ["batch", 1], ["channel", 2], ["time", "dynamic"] ],
"window": { "min": 2048, "max": 8192 }, "overlap": 1024, "latency": 512 }
]
}
Key |
Meaning (Models and tensors) |
|---|---|
|
One entry per export: |
|
The specs: |
|
The plan the handler starts on, spelled as an entry’s |
|
|
The contract file#
One root, "hard" or "async"; edge_cost and host_domains stand beside either. The
defaults, spelled out (the bundled files spell the budget and the warm-up; the RAVE encoder and
decoder files add "on_miss": "zeros"):
{
"hard": {
"budget": "measured",
"warmup": "until_stable",
"on_miss": "bypass"
}
}
Key |
Meaning (Contracts) |
|---|---|
|
Optional, any number (a fractional block included): the blocks in anchor elements, the rate
in anchor elements per second; a host patches them in with |
|
|
|
|
|
|
|
A number |
|
|
|
|
|
|
|
|
The contract has no writer: write a {"hard": ...} file by hand from what
ContractHandle::hard() reads back.
The context file#
{
"num_threads": 4,
"wait_strategy": "blocking",
"log": { "level": "warning", "drain": "thread", "queue_capacity": 512, "drain_interval_ms": 10 },
"provider_options": { "sets": [
{ "engine": "onnxruntime", "provider": "cuda", "options": { "device_id": "0" } }
] }
}
num_threads (absent: ANIRA_THREADS_AUTO; 0: the host brings its own threads),
wait_strategy, the log block, the device blocks cuda, gl, vulkan, metal,
d3d12 and webgpu (which imply a device anira owns; a borrowed handle is set in code, with the
device setter after loading), and the
provider_options extension (The context). The 2.x top-level log_level is refused:
write log.level.
In C#
The same three loaders: anira_model_config_from_json / anira_model_config_from_json_file,
anira_contract_from_json and anira_context_config_from_json; the writers
anira_model_config_to_json and anira_context_config_to_json take (buf, cap, out_len) and
return ANIRA_ERROR_BUFFER_TOO_SMALL with the length in out_len, so call once with a NULL
buffer to size it. to_json() writes the version 3 spelling in a fixed key order.
Note
The loaders read a 2.x document (inference_config / context_config roots) too and
upgrade it in memory (ANIRA_SUCCESS_UPGRADED, upgraded());
ModelConfig::take_legacy_contract() hands out the Hard contract it held back.
JSON files maps the keys.