--- title: "Component Libraries" description: "Upload, activate, version, and manage component library packages" source_url: https://ai-ops.com/docs/components/libraries --- # Component Libraries Navigate to **Components > Libraries** to manage component library packages. A library is a `.kcl` (Koios Component Library) file containing one or more component types that can be instantiated on an environment canvas. --- ## Library List The library list page shows all uploaded libraries grouped by name. Each row displays: | Column | Description | |--------|-------------| | **Name** | Library name | | **Versions** | Number of uploaded versions | | **Components** | Number of component types in the active version | | **Status** | Whether the library has an active version | | **Created** | When the first version was uploaded | | **Description** | Library description from the package metadata | Click a row to open the library detail page. --- ## Uploading a Library 1. Click **Upload Library** at the top of the list page 2. Drag and drop a `.kcl` file into the upload area (or click to browse) 3. Koios validates the package metadata and extracts component definitions 4. On success, you are taken to the library detail page > [!NOTE] File format > Libraries must be packaged as `.kcl` files using the Koios Component Builder. See [Building Components](https://ai-ops.com/docs/components/building-components.md) for details. If this is the first version of a new library, it is automatically activated. If you are uploading a new version of an existing library, you will be prompted to review and activate it. ### Upload Limits and Safety - **Maximum size: 500 MiB.** Uploads above this size are rejected before the file is read into memory. A full data-science stack (numpy + pandas + scipy + sklearn) lands around 110 MiB, leaving plenty of headroom for typical ONNX bundles and additional dependencies. - **Safe extraction.** The platform rejects archives that contain path-traversal entries (zip slip), absolute paths, or malformed member names. Bundled wheels are extracted into an isolated location and their metadata is filtered before installation. - **Library name validation.** Library names are restricted to lowercase letters, digits, hyphens, and underscores. Uploads with invalid names are rejected at the validation step. --- ## Library Detail The library detail page has four tabs: ### Overview Shows all uploaded versions of this library, sorted by version number (newest first). Each version row shows: - **Version** — semantic version (e.g., `1.2.0`) - **Status** — Active, Inactive, or Invalid - **Created** — upload date - **Instances** — how many component instances use this version - **Actions** — Activate, View, or Delete ### Components Lists all component types defined in this library. Click a component to view its full specification: - **Inputs** — fields that receive data (name, type, description, default value) - **Outputs** — fields that produce data - **Configuration** — static settings that don't change at runtime (with constraints like min/max values and dropdown choices) ### Dependencies Shows the library's package dependencies: - **Bundled Packages** — third-party packages that are included in the `.kcl` file and installed when the library is activated - **Platform Packages** — packages that are already pre-installed in the Koios container and do not need to be bundled. If a dependency is satisfied by a platform package, it is listed here with the installed version. ### Documentation If the library includes documentation (a README), it is rendered here. ### Danger Zone Permanently delete all versions of this library. You must type the library name to confirm. If any instances exist, they will also be deleted. --- ## Activating a Version Only one version of a library can be active at a time. The active version determines which component types are available on the canvas. To activate a different version: 1. Open the library detail page 2. On the **Overview** tab, click **Activate** next to the version you want 3. A migration preview appears showing: - **Component changes** — which component types were added, removed, or modified - **Affected instances** — which existing instances will be migrated or deleted - **Wires to remove** — any wires that connect to fields that no longer exist 4. Review the changes and click **Activate** (or **Upgrade** / **Downgrade** depending on the version direction) > [!WARNING] Removed components > If a component type was removed in the new version, all instances of that type will be permanently deleted along with their wires. The migration preview shows exactly what will be affected before you confirm. Koios automatically detects whether the activation is an upgrade, downgrade, or lateral move based on semantic versioning. --- ## Versioning Libraries use [semantic versioning](https://semver.org/) (`major.minor.patch`) with optional pre-release tags (e.g., `1.0.0-beta.1`). When you upload a new version of an existing library: - The new version appears as **Inactive** in the version list - The previously active version remains active until you explicitly activate the new one - You can have multiple inactive versions uploaded at the same time - Activating a version migrates all existing instances to the new component definitions --- ## What's Next - [Component Environments](https://ai-ops.com/docs/components/environments.md) — create an execution context for your components - [Component Canvas](https://ai-ops.com/docs/components/canvas.md) — add instances of library components to an environment - [Building Components](https://ai-ops.com/docs/components/building-components.md) — create your own component libraries