Assigning Bindings

What Are Bindings?

Bindings connect your AI model to live data. Every model has inputs (data the model reads) and outputs (predictions the model writes). Bindings map each input and output to a tag — a live data point collected from a connected device.

Without bindings, the model has no data to process and nowhere to write its results. Once bindings are assigned and configured, the Predict Engine automatically feeds live tag values into the model at each scan cycle and writes the model's predictions back to the output tags.

Tags (live data)          Model               Tags (predictions)
┌──────────────────┐    ┌───────────┐    ┌──────────────────────┐
│ Temperature  ────│───►│           │───►│  Predicted Failure   │
│ Pressure     ────│───►│   ONNX    │───►│  Recommended Action  │
│ Flow Rate    ────│───►│   Model   │    └──────────────────────┘
│ Vibration    ────│───►│           │
└──────────────────┘    └───────────┘
     Input Bindings                        Output Bindings

How the Predict Engine Uses Bindings

At each scan cycle, the Predict Engine:

Reads the recent history of each input tag (the number of samples depends on the model's sample_rate configuration)
Calibrates each value by applying the binding's gain and bias (no-op when both are at defaults)
Normalizes each value according to the binding's scaling configuration (e.g., Min-Max scales to 0–1)
Runs inference — feeds the normalized input history through the model
Denormalizes each output back to real-world units
Calibrates inversely on outputs to convert from model space back to engineering units
Writes the result to each output tag
Validates that input values are within expected ranges (failure detection)

This happens automatically and continuously once the model is enabled.

The Bindings Tab

Navigate to a model's detail page and select the Bindings tab. The tab displays a two-column layout:

Left column — Input bindings (data the model reads)
Right column — Output bindings (predictions the model writes)

Each binding appears as a card showing:

Binding order number — the position in the model's input or output array
Tag name — the assigned tag, or "Unassigned" if no tag is linked
Live values — for inputs, the raw tag value and its normalized model input; for outputs, the model's raw output and the denormalized tag value
Failure bounds — the expected value range for failure detection
Status indicator — running, stopped, error, or unassigned

Bindings are created automatically

When you upload a model file, Koios reads the model's input and output dimensions and creates the corresponding bindings automatically. You don't create bindings manually — you assign tags to them.

Assigning a Tag

Click any binding card to open its configuration drawer. The Tag section at the top contains a tag picker where you assign which tag feeds data into (or receives data from) this binding.

Click the binding card to open the drawer
In the Tag section, use the tag picker to search and select a tag
The binding saves automatically when you close the drawer

For output bindings, the tag picker only shows writable tags — tags configured with output usage that can accept written values.

Assign all input bindings

A warning appears on the Bindings tab if any input bindings are unassigned. The model cannot run inference correctly with missing inputs.

Training Metadata

If the model file includes training metadata (embedded via koios-model-utils), each binding may show a "From training" info box. This displays the binding's original name and description from training, helping you match bindings to the correct tags. For example, a binding named temperature_sensor_1 tells you which physical measurement it expects.

Scaling (Normalization)

Most ML models expect inputs in a specific numeric range (e.g., 0 to 1, or -1 to 1). Raw tag values like temperature (20–200) or pressure (0–500) need to be scaled before the model can process them. The Scaling section configures this transformation.

Scaling Methods

Method	Formula	Output Range	Use Case
None	No transformation	Raw values	Model trained on raw data
Min-Max	(value - min) / (max - min)	0 to 1	Most common for neural networks
Symmetric	2 * (value - min) / (max - min) - 1	-1 to 1	Models using tanh activation
Z-Score	(value - mean) / std	Centered at 0	Standardized features

Parameter Source

When using Min-Max or Symmetric scaling, you choose where the min/max parameters come from:

Tag Range — Uses the rangeMin and rangeMax configured on the assigned tag. This is convenient when your tag ranges already match the training data ranges.
Custom — You provide explicit minimum and maximum values. Use this when the tag range doesn't match what the model was trained on.

Z-Score always uses Custom

Z-Score normalization requires a mean and standard deviation, which cannot be derived from a tag's range. When you select Z-Score, the source is automatically set to Custom and you enter the mean and standard deviation values.

Clamp Output

For output bindings, an optional Clamp Output toggle constrains the model's prediction to the binding's configured range. When enabled, if the model produces a value outside the normalization bounds, it is clamped to the minimum or maximum before being written to the tag. This prevents unexpected extreme values from reaching the output device.

Output Index

For models that forecast multiple future time steps (output depth > 1), each output binding has an Output Index setting (1-based) that selects which time step to use as its prediction. For example, if a model outputs 12 future steps and you only care about step 12, set the output index to 12. See Model Inference Requirements for details on multi-step output shapes.

Calibration (Gain & Bias)

Every binding can apply a linear transform on top of the raw value. The Scaling tab exposes two fields:

Field	Default	Description
Gain	`1.0`	Multiplier applied to the value. Cannot be zero.
Bias	`0.0`	Offset added after the gain.

Use calibration to correct sensor drift, convert engineering units, or fine-tune a model's response — without retraining or re-uploading the model file. Both values are non-nullable and default to the identity transform, so existing bindings see no change after upgrading to v1.1.0.

How Calibration Is Applied

Input bindings:

calibrated_value = (raw_tag_value × gain) + bias

Calibration runs before range checks, rate-of-change detection, and normalization, so every downstream check operates in the calibrated value space. If your gain or bias is non-default, the normalization source is automatically set to Custom — the tag's native range no longer matches what the model sees.

Output bindings (inverse):

tag_value = (denormalized_model_output − bias) / gain

Calibration is the final step before the value is written back to the tag.

When to use calibration vs normalization

Use normalization to match the value range the model was trained on. Use calibration for physical-world adjustments — a sensor that reads 2°C low, a transducer with a 0.98 scale factor, a setpoint that needs to be offset by 5 units. The two are independent and compose cleanly.

Failure Detection

Failure detection monitors whether input values fall outside expected bounds. If an input is out of range, it may indicate a sensor fault, a disconnected device, or abnormal process conditions — any of which could cause the model to produce unreliable predictions.

Failure Range Mode

Mode	Behavior
Disabled	No range checking performed
Normalization Range	Uses the same min/max bounds configured in the Scaling section
Custom	You provide separate minimum and maximum failure bounds

Failure Evaluation

When the model uses interpolated samples (multiple data points per scan), this setting controls how samples are evaluated against the failure bounds:

Evaluation	Behavior
Any	Fails if any single sample is out of range
Latest	Only checks the most recent sample
Average	Checks the average of all samples

Failure Debounce

The debounce count prevents transient spikes from triggering failures. Set the number of consecutive scans that must fail before the binding enters a failure state. A value of 0 means failure triggers immediately on the first out-of-range scan.

Recovery Hysteresis

Once a binding enters a failure state, it doesn't recover the instant values return within bounds. The hysteresis percentage defines how far inside the range values must return before the binding recovers. This prevents rapid toggling between failed and healthy states when values hover near the boundary.

For example, with a range of 0–100 and 5% hysteresis, a failed binding only recovers when the value drops below 95 (or rises above 5).

Rate of Change Detection

Rate of Change (ROC) detection flags values that are changing too quickly, which can indicate equipment malfunction, sudden process upsets, or noisy sensors even when the value itself is within the normal range.

Setting	Description
ROC Enabled	Toggle rate-of-change detection on or off
ROC Threshold	Maximum allowed change per minute
Threshold Mode	Express the threshold in raw units per minute or as a percentage of the normalization range per minute
Direction	Detect rising changes, falling changes, or both
ROC Window	Time window (in seconds) over which the rate of change is calculated

Stale Data Detection

The Allowed Missed Samples setting controls how many consecutive scan cycles a tag can miss (produce no new data) before the binding is flagged as stale. This protects against situations where a device disconnects or a tag stops updating — the model would otherwise keep using the last known value indefinitely.

Binding Name and Description

Each binding has an editable name and description visible at the top of the configuration drawer. Click either field to edit it inline. If the model file included training metadata, the name and description are auto-populated from the metadata.

These fields are for your reference only — they help you identify which physical measurement or prediction each binding represents. They do not affect how the Predict Engine processes the binding.

Typical Workflow

Upload a model file — bindings are created automatically from the model's input/output dimensions
Review training metadata — if present, use the binding names to understand what each input/output expects
Assign tags — click each binding and select the appropriate tag
Configure scaling — set the normalization method and parameters to match how the model was trained
Set failure detection — define acceptable ranges to catch sensor faults or abnormal data
Enable the model — once all bindings are assigned and configured, enable the model to start inference

Match your training configuration

The scaling method and parameters must match how the model was trained. If the model was trained with Min-Max normalization using a range of 0–500 for a pressure input, configure that binding with Min-Max scaling and Custom source with minimum 0 and maximum 500.

What's Next

Configuring a Model — scan rate, sample rate, on-demand, and other model settings
On-Demand Inference — synchronize inference with fresh device data
Monitoring a Model — live values, diagnostics, execution performance, and trends
Managing Model Files — embedded metadata that auto-populates binding settings

Managing Model Files Configuring a Model