Versioning and format stability

This page describes how kLLM versions are numbered, which interfaces a version number covers, and how the formats of sealed checkpoints and key files are identified.

Version numbers

kLLM intends to follow Semantic Versioning. A version has the form MAJOR.MINOR.PATCH:

MAJOR increases for incompatible changes to a stable interface;
MINOR increases for new, backward-compatible functionality;
PATCH increases for backward-compatible fixes.

Development versions carry a .devN suffix, as defined by PEP 440. The version is set in pyproject.toml and in src/kllm/__init__.py, and kllm version prints it:

$ kllm version
kllm 0.1.0.dev0

A release is a Git tag of the form vMAJOR.MINOR.PATCH. The release workflow builds the package for each such tag and publishes it to PyPI.

Note

No version has been tagged or published on PyPI yet. pip install kllm becomes available with the first tagged release; until then, install from a source checkout. See Installation guide.

Pre-1.0 status

kLLM is in its 0.x series. Following Semantic Versioning, a 0.x minor release may contain incompatible changes. kLLM’s intent for the 0.x series is:

a patch release does not change the command-line interface, the environment variables or the sealed-checkpoint and key-file formats in an incompatible way;
a minor release may change them; the release notes then state the change and the action it requires, such as resealing a model;
a development version (.devN) carries no compatibility commitment.

The interfaces that a version number covers are:

Interface	Reference
The `kllm` command, its subcommands, options and defaults	Command-line reference
The environment variables that kLLM reads or sets	Settings
The `kllm.keysource` entry-point group for key sources	Registering a key source
The layout of sealed checkpoints and the key-file format	This page and Sealed checkpoint format

Other Python modules of the kllm package are internal. They may change in any release before 1.0.

The engine extras require SGLang 0.5 or later (serve) and vLLM 0.11 or later (vllm). The published measurements were made with SGLang 0.5.21 and vLLM 0.31.0. A new engine release can change engine behavior independently of kLLM’s version.

Sealed-format compatibility

Every artifact that kLLM writes carries an explicit format identifier. kLLM checks the identifier before it uses the artifact and refuses an artifact whose identifier it does not recognize, instead of serving it incorrectly.

Artifact	Identifier in 0.1.0.dev0	Where it is recorded
Sealed LLM	scheme `l1`	`config.json`, key `kllm.scheme`. The `kllm` section also records the transform (`orth` or `perm`), the key fingerprint, the base architecture and the number of regular token ids.
Sealed MiniMax H3 pipeline	scheme `l1`	`kllm.json` at the top of the pipeline directory, with the transform, the key fingerprint and the architecture.
Keyed Z-Image pipeline	scheme `d1-v1`	`kllm.json`, with the key fingerprint and the architecture.
Client-keyed Z-Image pipeline	scheme `client`	`kllm.json`.
Encrypted tokenizer and trusted tensors	magic bytes `KLLMBLOB1` followed by a newline	The first bytes of `trusted.kllm`. A JSON header follows, with the key fingerprint; the payload is encrypted with AES-256-GCM in chunks of 64 MiB.
Key file	`"format": "kllm-key"`, `"version": 1`	The JSON key file, by default `~/.kllm/keys/default.key`. The 256-bit key is encrypted with AES-256-GCM under a key derived from the passphrase with scrypt.

The checks in 0.1.0.dev0 behave as follows:

kllm serve --key serves only sealed LLMs and MiniMax H3 pipelines with scheme l1. For any other scheme it stops with a message that names the scheme. A model sealed for client-keyed mode is directed to kllm serve --client.
A model sealed under a different key is refused; the message names both key fingerprints.
A trusted.kllm file without the KLLMBLOB1 magic is rejected as not being a kLLM trusted blob. A modified, reordered or truncated file fails authentication and is rejected.
A key file whose format is not kllm-key or whose version is not 1 is rejected as not being a kLLM v1 key file.

Everything secret in a sealed model is derived from the 256-bit key with HKDF-SHA256 and the salt kllm/v1. A change to the transforms or to this derivation changes the sealed weights that a given key produces.

kLLM’s intent for format changes is:

a change that alters how an existing artifact must be read, including a change to the transforms or to the key derivation, receives a new identifier; an existing identifier does not change its meaning;
key files of version 1 remain loadable, so that a model can be resealed under the same key after a format change;
when a minor release stops accepting an identifier, the release notes say so, and the model is resealed from its original checkpoint with kllm seal.

Important

Keep the original checkpoint and the key file. Resealing requires both. Without the key file and its passphrase, a sealed model cannot be served, and kLLM provides no way to recover a lost key.

A sealed checkpoint does not record the kLLM version or the engine version that produced or served it. The engine loads a sealed LLM with its stock model class, so an engine upgrade does not change the sealed format; the engine must still support the model architecture.

Note

Part of the upcoming 0.2 line: a store record per model in the local store (.DIRECTORY.kllm-store.json, next to the model directory), which records the source repository and revision, the digest of every file and, for a sealed model, the transform and key fingerprint (Store record and manifests). A catalog model also carries its published kllm-manifest.json, which records the kLLM version that built it. Recording the engine version and a test report is planned. See Roadmap.