Model Metadata Library

koios-model-utils writes the metadata Koios reads when you upload an ONNX model: what each input and output means, how values are normalized, and how often the model expects to run.

Bring your own ONNX file from any framework. The library only touches metadata, so it never re-encodes or re-optimizes the graph.

Without it you can still upload a model and configure everything by hand. With it, the model arrives already describing itself, and Koios fills in the bindings, normalization rules, sample rate, and action map for you.

Installation

pip install koios-model-utils

The only runtime dependency is onnx. No training framework, no command-line tool.

Annotating a model

import onnx
from koios_model_utils import (
    Algorithm,
    InputBinding,
    NormalizationSource,
    NormalizationType,
    OutputBinding,
    TrainingMeta,
    embed_koios_metadata,
)

model = onnx.load("my_model.onnx")

embed_koios_metadata(
    model,
    inputs=[
        InputBinding(name="tank_temperature", description="Tank temperature (C)"),
        InputBinding(name="pressure", description="Vessel pressure (kPa)"),
    ],
    outputs=[
        OutputBinding(
            name="valve_position",
            range_min=0.0,
            range_max=100.0,
            normalization_type=NormalizationType.SYMMETRIC,
            normalization_source=NormalizationSource.CUSTOM,
            custom_minimum=0.0,
            custom_maximum=100.0,
            clamp_output=True,
        ),
    ],
    training=TrainingMeta(
        scenario_name="tank_temperature",
        algorithm=Algorithm.PPO,
        obs_depth=5,
        sample_rate=1.0,
    ),
)

onnx.save(model, "my_model_koios.onnx")

Upload the saved file as you would any other model. See Creating a Model and Assigning Bindings for what happens next.

Reading metadata back

from koios_model_utils import parse_koios_metadata

parsed = parse_koios_metadata(onnx.load("my_model_koios.onnx"))
parsed.training      # TrainingMeta, or None
parsed.inputs        # list[InputBinding]
parsed.outputs       # list[OutputBinding]
parsed.has_metadata  # True if any Koios metadata was present

If the metadata has already been extracted from the file and stored elsewhere, parse_koios_metadata_from_dict takes the decoded dictionary directly.

What you can declare

Every class validates on construction, so a combination that cannot work — Z-score normalization together with a custom minimum, for example — raises immediately rather than at upload.

NormalizationType, NormalizationSource, ModelType, OutputMode, Algorithm and FailureRangeMode are string enums. The classes accept plain strings too, but passing enum members catches typos before you ever build the file.

Parsing failures raise KoiosMetadataError, UnsupportedSchemaVersionError, or KoiosMetadataDecodeError.

Sample rate and scan rate

These are different settings and the distinction matters.

Sample rate is the interval the model was trained at. Koios resamples historical inputs to this rate before running the model.

Scan rate is how often Koios executes the model. Leave it unset and it follows the sample rate, which is what you want for a forecasting model trained and run at the same cadence. Set it explicitly when a controller needs to act faster than the simulator step it was trained against — a one-second history lookback driving a control loop that runs ten times a second.

See Configuring a Model.

Models that emit an action index

For a model that returns a choice rather than a continuous value, set the output mode and supply an action map:

from koios_model_utils import ActionMapEntry, OutputMode, TrainingMeta

training = TrainingMeta(
    algorithm="DQN",
    output_mode=OutputMode.DISCRETE,
    action_map=[
        ActionMapEntry(value=-1.0, label="Decrease setpoint"),
        ActionMapEntry(value=0.0, label="Hold"),
        ActionMapEntry(value=1.0, label="Increase setpoint"),
    ],
)

The labels are what an operator sees when the model fires, so write them for that reader. action_map also accepts plain dictionaries with value and label keys.

Versioning

The metadata format is at schema version 1, and the library moves in step with the platform. A model annotated by a newer library than your Koios version may carry fields that version does not read; it still uploads, and the unknown fields are ignored.