Building Components

The Koios Component Builder lets you build custom component types in Python, package them as libraries, and upload them to Koios for real-time execution. This page provides a high-level overview of the development workflow. For complete documentation, examples, and API reference, see the Koios Component Builder documentation.

Overview

A component is a Python class that defines typed inputs, outputs, and configuration fields. The component engine calls your execute() method on every scan cycle, passing in the latest input values and reading back your outputs.

from koios_component_builder import Component, Input, Output

class TemperatureConverter(Component):
    """Converts Celsius to Fahrenheit."""

    celsius: Input[float] = Input(default=0.0, description="Temperature in Celsius")
    fahrenheit: Output[float] = Output(default=32.0, description="Temperature in Fahrenheit")

    def execute(self) -> None:
        self.fahrenheit = self.celsius * 9 / 5 + 32

When deployed to Koios, this component appears on the canvas with a celsius input port and a fahrenheit output port. Wire a tag to the input, wire the output to another tag or component, and the conversion runs automatically at the environment's scan rate.

Development Workflow

1. Write          2. Package         3. Upload          4. Wire & Run
   Component  ───►   .kcl file  ───►   to Koios    ───►   on Canvas
   (Python)        (CLI tool)        (drag & drop)      (visual editor)

1. Write your component classes using the SDK's base classes and field descriptors
2. Package them into a library using the koios-component-builder CLI tool
3. Upload the .kcl file through the Koios UI at Components > Libraries
4. Wire instances on an environment canvas and enable the environment

What You Can Build

Key Concepts

Fields

Components declare their interface using typed field descriptors:

State

Components can maintain internal state between execution cycles. Instance variables set in __init__ or during execute() persist across cycles — useful for integrators, moving averages, edge detectors, and any logic that depends on previous values.

Libraries

Components are organized into libraries. A library is a named, versioned collection of component types. When you upload a new version of an existing library, Koios offers a migration flow that maps existing instances to the updated component definitions.

Metadata

Each component can declare visual metadata (icon, category, canvas width) that controls how it appears on the canvas. The SDK provides a catalog of icons and categories to choose from.

Pin Layout (SDK v3)

By default, pins appear on the canvas in declaration order. To control ordering and grouping, declare inputs_layout and outputs_layout on the component's Meta class:

from koios_component_builder import Component, Input, Output, Gap

class PIDController(Component):
    sensor: Input[float] = Input(default=0.0)
    setpoint: Input[float] = Input(default=0.0)
    enable: Input[bool] = Input(default=True)
    output: Output[float] = Output(default=0.0)

    class Meta:
        inputs_layout = ["sensor", "setpoint", Gap(), "enable"]
        outputs_layout = ["output"]

Gap() (or Gap(size=2) for wider spacing) inserts visual separation between pins. The layout you declare is the component-type default — users can override it per instance on the canvas.

Meta.inputs_layout and Meta.outputs_layout replace the older FieldDescriptor(order=...) convention, which is deprecated in SDK v3.

Wire Contract

The koios_component_builder.wire_contract module exposes the platform's canonical pin type vocabulary (int, float, bool, str, list, dict, plus the HistoryProvider sentinel) and the coercion rules that the canvas and engine enforce. Use it if you need to validate wire compatibility outside the platform — for example, in unit tests for a custom component library — so your assertions match what Koios actually allows.

Getting Started

For the full development guide — including installation, field types, configuration options, testing, packaging, and example components — see the Koios Component Builder documentation.

The builder repository includes:

• Installation and setup instructions
• Complete API reference for all field types and base classes
• A core library with 35+ example components (math, logic, control, signal processing)
• CLI reference for packaging and exporting libraries

What's Next

• Component Libraries — upload your packaged library to Koios
• Component Canvas — wire instances of your components to tags and other components
• Component Environments — configure scan rates and monitor execution