kolm manual · the spec

How kolm actually works.

Architecture, formats, formulas, registries. Everything below is what makes the contract above , kolm compile <task> in, signed local artifact out, actually true.

Contents.

1 · Architecture.

kolm compile is the orchestrator. Beneath it, four engines do the work, but the user only ever sees the compiler.

kolm compile <task> │ ▼ ┌─────────── Compile Orchestrator ───────────┐ │ │ ▼ ▼ ▼ ▼ ┌────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ RECALL │ │ DISTILL │ │ DECOMP │ │ RUN │ │ (4) │ │ (2) │ │ (1) │ │ (3+0) │ └────────┘ └─────────┘ └─────────┘ └─────────┘ │ │ │ │ ▼ ▼ ▼ ▼ multimodal k-sample recipe deploy + embed + frontier + pack from sign + index verify = observed bundle user data labels patterns artifact

Recall feeds Distill (every k-sample is grounded in recalled chunks). Distill produces labels for the LoRA half (the "make-the-model-yours" step) and observes deterministic patterns to seed the recipe pack (the "make-the-model-fast" step). Decompose finalizes the recipe pack indexed by embedding-shape of recalled context. Run loads model + LoRA + recipe pack + sqlite-vec index and the four work together at every token. That composition is the product.

2 · The K-score.

Named after Kolmogorov complexity. Every .kolm ships a single composite number that captures what we mean by a good compile: high accuracy, broad coverage, small size. Bigger is better.

K = accuracy × coverage × 1000 / log₂(size_kb + 2)
{ "k_score": { "composite": 412.7, "accuracy": 0.965, // pass-rate on embedded eval suite "coverage": 0.92, // share of inputs handled w/o LoRA fallback "size_bytes": 2348, // the actual signed zip on disk "p50_latency_us": 1400, // median over the embedded eval set "cost_usd_per_call": 0, // after compile, frontier cost amortized "spec": "k-score-1" } }

The score makes a compiler-cache hit visible: every successful compile is a small, fast, accurate artifact that didn't exist before. The K-score is the receipt that says exactly how small, fast, and accurate.

3 · The .kolm format.

A .kolm is a zip with seven well-known entries. Open it with any zip tool; verify it with kolm inspect. spec: "kolm-1" in the manifest pins the format version.

# mandatory manifest.json # task, base_model, runtime, k_score, evals stub, recipes stub, hashes recipes.json # the deterministic draft pack (RS-1) signature.sig # HMAC-SHA256 over canonical(manifest.json), KOLM_ARTIFACT_SECRET evals.json # {n, cases:[{id, input, expected}], spec:"evals-1"} # optional, present once Sprint 3 lands model.gguf # base model bytes (or a URL pointer for cloud-runtime artifacts) lora.bin # task-specific LoRA delta index.sqlite-vec # corpus index for offline recall

4 · Signature chain.

One signature, every byte covered. signature.sig is HMAC-SHA256 over the canonical JSON of manifest.json. The manifest carries SHA-256 hashes of every other entry, so signing the manifest signs the bundle.

{ "spec": "kolm-1", "job_id": "job_abc", "task": "classify support tickets", "runtime": { "engine": "recipe-only", "version": "0.1.0" }, "recipes": { "n": 26, "sha256": "..." }, "evals": { "n": 12, "sha256": "..." }, "k_score": { "composite": 412.7, ... }, "created_at": "2026-05-06T18:42:11Z" }

5 · Recipe registry (RS-1).

MITRS-1 Recipe is the calling convention, the deterministic-token subset of model behavior. Each recipe is a named, versioned, signed function over JSON: { id, name, version_id, input_schema, output_schema, source }. kolm compile emits the artifact's recipe pack as a recipes.json slice of the global RS-1 registry; every successful compile auto-merges new draft patterns back upstream.

6 · Recipe Speculative Decoding.

Standard speculative decoding uses a small model as the draft. RSD uses the registry. For any prefix whose shape matches a registered draft, we emit the draft tokens directly and verify against the target model in parallel. Coverage is the fraction of tokens where a draft existed; latency drops with coverage. Sprint 2 ships the prototype with a --decompose flag on kolm compile.

7 · Receipts (RS-1-receipts).

Every kolm run emits a structured rs-1-run receipt. Every /v1/wrap/verified call emits a rs-1-verified receipt with k-sample count, verifier pass/fail, winner index, and a signed reference to the artifact + recipe ID that handled the call. Save it, ship it, audit it, chain it.

8 · MCP integration.

kolm serve --mcp starts a stdio JSON-RPC server speaking protocolVersion: "2024-11-05". Every .kolm in ~/.kolm/artifacts/ becomes one MCP tool. tools/list returns name + K-score-bearing description; tools/call dispatches via artifact-runner.js; the response carries a _kolm block with the receipt and recipe ID. Frontier agents, Claude Desktop, Cursor, Codex, wire it up with three lines of config.