Model Inference Requirements

This page explains how Koios prepares data for your model and what shape your exported model file needs to be. Koios is an inference engine — models must be trained externally and exported as ONNX or TFLite.

Input Tensor Shape

Koios supports two input shapes — pick the one that matches how your model was trained:

Koios detects the shape from the model graph at upload time and validates it against the model's embedded metadata. Model list and detail pages label each model as "5 inputs, depth 1" (flat) or "5 inputs, depth 6" (time-series) so you can tell them apart at a glance.

In both shapes:

• Batch size is always 1.
• num_inputs is the number of input features, one per input binding.
• input_depth (rank-3 only) is the number of historical time steps Koios queries per scan.

Flat models (rank-2)

A flat model reads three input tags as a single row:

Binding 1        Binding 2        Binding 3
                Supply Temp °C   Return Temp °C    Fan Speed %
                (normalized)     (normalized)      (normalized)
              ┌─────────────────────────────────────────────────┐
  current     │     0.47             0.60             0.83      │
              └─────────────────────────────────────────────────┘
Shape: [1, 3]   No time dimension — just the most recent sample per binding.

Time-series models (rank-3)

A time-series model reading the same three tags with input depth 6 and sample rate 10s:

Binding 1        Binding 2        Binding 3
                Supply Temp °C   Return Temp °C    Fan Speed %
                (normalized)     (normalized)      (normalized)
              ┌─────────────────────────────────────────────────┐
  t₀ (oldest) │     0.42             0.65             0.80      │
  t₁ (-40s)   │     0.43             0.64             0.80      │
  t₂ (-30s)   │     0.45             0.63             0.81      │
  t₃ (-20s)   │     0.44             0.62             0.79      │
  t₄ (-10s)   │     0.46             0.61             0.82      │
  t₅ (newest) │     0.47             0.60             0.83      │
              └─────────────────────────────────────────────────┘
Shape: [1, 6, 3]   Time flows top → bottom. Columns ordered by binding order.

Key Rules

• Batch size is always 1
• Time flows forward in rank-3 — row 0 is oldest, last row is newest
• Columns match binding order — binding 1 is column 0, binding 2 is column 1, etc.
• Values are normalized (unless using "None" normalization)
• Input shape is fixed — read from your model file and cannot be changed after upload

Data Preparation Pipeline

On every scan, Koios:

1. Query — fetch historical data for each input tag covering input_depth × sample_rate seconds
2. Interpolate — resample to an evenly-spaced time grid using PCHIP interpolation (monotone cubic, no artificial peaks)
3. Normalize — scale each value using the binding's normalization type and source
4. Assemble — stack columns by binding order, wrap in batch dimension → [1, input_depth, num_inputs]

Output Tensor Shape

Three output shapes are supported:

Model File Requirements

What Koios Reads from Your File

Shape Convention

Koios accepts two input shapes:

• Flat: [batch_size, features] — no time dimension; used by single-step models (RL policies, regressors, classifiers)
• Time-series: [batch_size, time_steps, features] — time/depth dimension must be static
• Output: [batch, time, features], [batch, features], or scalar
• Data type: float32
• ONNX: batch dimension can be dynamic; time dimension must be static
• TFLite: input must have at least 2 dimensions

Quick Reference