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.

An ONNX file can carry this information itself — see the Model Metadata Library.

Input Tensor Shape

Koios supports three 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), "5 inputs, depth 6" (time-series), or "5 inputs, flat dim 42 (Structured)".

Across all three 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_dim (structured only) is the total length of the flat vector — the sum of every input's window length.

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.

Structured models (rank-2, carved into per-input windows)

A structured model file declares an input space: the flat input vector is divided into named inputs, and each one carries its own window length, sample rate, and interpolation method. Instead of one model-wide sample rate and depth, a flow reading sampled every second and a temperature sampled every hour can feed the same model.

At scan time Koios resamples each input on its own cadence against a single shared reference instant and lays the windows end to end into the vector the model was trained on. Staleness and history-depth checks are sized per input. The slices must tile the model's input dimension exactly — the upload dialog checks this before the file is accepted.

Because a structured file is rank-2, its per-input windows are declared in the file rather than derived from the graph. See Structured Input Spaces for how a space is declared and carved, and Assigning Bindings for the per-input sampling controls.

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 three 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
• Structured: [batch_size, flat_dim]. Rank-2, with the per-input windows declared in the file's embedded input space
• Output: [batch, time, features], [batch, features], or scalar
• Data type: the graph's own floating-point type is used, so single-precision (float32) and double-precision (float64) files both run. Quantized integer inputs are not supported
• ONNX: batch dimension can be dynamic; time dimension must be static
• TFLite: input must have at least 2 dimensions

Quick Reference