---
title: "Building Components"
description: "Overview of developing custom components with the Koios Component Builder"
source_url: https://ai-ops.com/docs/components/building-components
---

# 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](https://github.com/Ai-Ops-Inc/koios-component-builder).

---

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

```python
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

```text
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

| Component Type | Description |
|---------------|-------------|
| **Data processing** | Scaling, filtering, moving averages, unit conversion |
| **Control logic** | PID controllers, setpoint management, cascade loops |
| **Decision logic** | State machines, alarm rules, threshold detection, latches |
| **Analytics** | Rolling statistics, trend analysis, anomaly detection |
| **Custom protocols** | Proprietary device adapters, data format converters |

---

## Key Concepts

### Fields

Components declare their interface using typed field descriptors:

| Field Type | Purpose |
|-----------|---------|
| **Input** | Receives data from a wired tag, another component, or a manual value |
| **Output** | Produces data that can be wired to tags or other components |
| **Config** | Static settings configured once per instance (numbers, text, booleans, dropdowns) |
| **HistoryInput** | Provides on-demand access to a tag's historical time-series data |

### 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:

```python
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](https://ai-ops.com/docs/components/canvas.md#per-instance-pin-layouts) 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](https://github.com/Ai-Ops-Inc/koios-component-builder).

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](https://ai-ops.com/docs/components/libraries.md) — upload your packaged library to Koios
- [Component Canvas](https://ai-ops.com/docs/components/canvas.md) — wire instances of your components to tags and other components
- [Component Environments](https://ai-ops.com/docs/components/environments.md) — configure scan rates and monitor execution