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).

Both formats must use float32 data type.

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.

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 — 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

Reset from Metadata

If a model has an active file with embedded metadata, you can re-apply it at any time using the Reset from Metadata action on the model's overview page. This updates configuration and binding settings from the metadata without affecting tag assignments.

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 depth, output depth, creation date. For discrete models, the action map editor.
Visualize	Interactive network graph of the model structure (rendered via Netron)
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