Managing Model Files

Model files contain the pre-trained neural network weights and structure that Koios uses for inference. Models must be trained externally and exported as ONNX or TFLite before uploading. Each model can have multiple file versions, but only one is active at a time.

Supported Formats

Format	Extension	Notes
ONNX	`.onnx`	Must not use external data files. Batch dimension can be dynamic; time/depth dimension must be static. IR version must be 13 or lower.
TFLite	`.tflite`	Must have at least 2 dimensions (batch and depth).

Inputs must be a floating-point type. Koios feeds each file the numeric type its graph declares, so single-precision (float32) and double-precision (float64) files both run. Files with quantized integer inputs are rejected rather than having their normalized values silently truncated.

Uploading a File

Open the model's Files tab and click Upload New File.

Field	Required	Description
File	Yes	Drag and drop or click to select an `.onnx` or `.tflite` file
Version	No	A label like `1.0.0` or `v2-beta`. Auto-generated if left blank (e.g. `warm-fox-12`). Must be unique per model.
Notes	No	Optional notes about this version

What Happens During Upload

Koios validates the file and extracts:

Property	Description
num_inputs	Number of input features (creates one input binding per feature)
num_outputs	Number of output features (creates one output binding per feature)
input_depth	Number of historical time steps the model expects
output_depth	Number of future time steps the model predicts (1 for single-step models)

If this is the model's first file, it is automatically activated and bindings are created. For subsequent uploads, you choose when to activate.

Input Shape

Every upload continues to an Input Shape step, where you confirm how Koios should read the file's input tensor. Four cards are offered, pre-selected from what was detected in the file:

Card	Shape	When it is selectable
Flat	`[1, N]`	Rank-2 files with no embedded input space
Time-series	`[1, D, F]`	Rank-3 files
Structured	`[1, flat_dim]`	Rank-2 files; pre-selected and locked when the file declares its own input space
Multi-input	`{a: …, b: …}`	Disabled — "Coming in a later release"

Cards that contradict the file are disabled with the reason shown on hover. A rank-3 file cannot be read as Flat or Structured, and a file that declares its own input space cannot be read as anything but Structured.

Choosing Structured on a file that does not already declare an input space opens the slice builder, where you carve the flat vector into named inputs and give each one a window length and sample rate. The builder shows each input's slot range live and checks that the slices tile the model's input dimension exactly. Click Save shape to finish. Flat and Time-series confirm immediately with no extra step.

Activating a File

When you upload a second or later file, Koios shows a post-upload step before activation:

Activation Preview

Before activating, Koios shows what will change:

Binding changes: if the new file has a different number of inputs or outputs, bindings will be added or removed. Existing bindings (and their tag assignments) are preserved where the binding order matches.
Action map diff (discrete models only): if the new file's action map differs from the current one, you can choose to keep the current map or use the new file's map.
Metadata preview: if the file contains embedded metadata, a summary shows what will be applied (see Embedded Metadata below). You can toggle this on or off.

Click Set as Active to activate, or Close to keep the current file active and activate later.

Activating Later

From the file version history on the Files tab, click the Set Active button on any inactive file. You'll see the same activation preview before confirming.

Binding Review

After activation, a review step lets you verify and edit binding names and descriptions. Named bindings enable fuzzy tag matching recommendations, so it's worth filling these in.

File Version History

The Files tab shows all uploaded versions in a timeline, newest first. The active file is marked with a checkmark and an Active badge.

Each version shows:

Version label and filename
Input/output counts and input depth
Creation timestamp
Action count (for discrete models)

Actions per File

Action	Description
Set Active	Activate this file (not shown on the currently active file)
View	Open the file's detail page with structure visualization and metadata
Download	Download the original file
Edit	Change the version label or notes
Delete	Remove this version (disabled for the active file)

Embedded Metadata

ONNX files can include Koios-specific metadata that is automatically applied to the model's configuration and bindings. This reduces manual setup, which is especially useful when deploying models from a training pipeline.

Evolving feature

Embedded metadata support is functional but still being expanded. The properties described below are supported today. Additional metadata fields and tooling for embedding them during training are planned.

How It Works

Metadata is stored as custom properties in the ONNX file's metadata_props, using keys prefixed with koios.. When a file with metadata is uploaded:

First file: metadata is applied automatically
Subsequent files: you can toggle "Apply metadata from this file" during activation

Training Metadata (`koios.training`)

Applied to the model's configuration:

Key	Applied To
`sample_rate`	Model's sample rate and scan rate
`model_type`	Output application (Absolute / Relative)
`output_mode`	Output mode (Continuous / Discrete)
`action_map`	Action map on the model file (discrete models)

Binding Metadata (`koios.bindings`)

Applied to each binding by binding order:

Key	Applied To
`name`, `description`	Binding name and description
`normalization_type`	Normalization type (None / Min-Max / Symmetric / Z-Score)
`normalization_source`	Normalization source (Tag Range / Custom)
`custom_minimum`, `custom_maximum`	Custom normalization bounds
`custom_mean`, `custom_std`	Custom Z-Score parameters
`range_min`, `range_max`	Failure range bounds

Input Space (`koios.observation_space`)

Files exported with a structured input space carry a third key describing that space: the input tree itself and a flat list of its leaves, each with its slice length, sample rate, and interpolation method.

Uploading a file that carries it marks the file's shape as Structured and stamps one input binding per leaf:

Key	Applied To
`path`	The binding's input path, used to group binding cards by input
`slice_length`	The binding's window length (how many samples this input contributes)
`sample_rate`	The binding's per-input sample rate
`interpolation`	The binding's interpolation method

All four leaf fields are owned by the file and are re-stamped on every activation, so activating a file replaces whatever the bindings held before. Sample rate and interpolation are editable between activations — see Assigning Bindings.

Reset from Metadata

If a model has an active file with embedded metadata, you can re-apply it at any time: open the three-dot menu in the model header and choose Reset from metadata. This updates configuration and binding settings from the metadata without affecting tag assignments. The item is greyed out when the active file carries no training metadata.

Viewing Metadata

Open the file's detail page (click View on any file version) and go to the Metadata tab to see the raw training and binding metadata extracted from the file.

File Detail Page

Each file version has its own detail page with:

Tab	Content
Overview	Input shape, output shape, creation date. For discrete models, the action map editor. A structured file reports its input count and flattened dimension here, for example "5 inputs, flat dim 42 (Structured)".
Visualize	Interactive network graph of the model structure (rendered via Netron)
Space	The file's structured input space as a tree, with each input's slice and window. Only shown when the file declares one.
Metadata	Training info and binding metadata extracted from the file (ONNX only)

What's Next

Assigning Bindings: connect model inputs and outputs to tags
Model Inference Requirements: tensor shape requirements and data preparation

Creating a Model Assigning Bindings