Module calibration 

W10 — Forge calibration pipeline (the training-related upgrade).

This is an upgrade of the existing forge, not a new forge: the forge already PRODUCES + CERTIFIES artifacts (it certifies GPU kernels against a CPU oracle and transcodes GGUF→p64). Calibration/adaptation artifacts — AWQ activation scales, int8-KV scales, sparse KV dictionaries — are the same produce-and-certify pattern applied to a new artifact class, so they live here as a calibration concern beside the kernel/transcode entry points. The engine still only RUNS certified artifacts.

Pipeline (5 stages): corpus → capture → learn → certify → package.

• corpus (corpus) — assemble/expand the calibration text. Local Ollama is a legitimate resource HERE (offline domain-diverse synthesis), strictly forge-side — it never enters the inference runtime (CLAUDE.md §1 holds).
• capture — run OUR engine over the corpus with instrumentation on (reuses llm_awq’s activation hooks; KV capture arrives with W5a). This CANNOT come from Ollama — the artifacts compress our engine’s own tensors (GQA layout, RoPE convention, layer shapes are engine-specific).
• learn — fit the artifact (AWQ scale fold reuses the existing AWQ pipeline; int8-KV scales = W5a; dictionary/Top-K SAE = W5b).
• certify ([certify]) — the ΔPPL ≤ gate via the existing [perplexity_eval_blocking] oracle.
• package (package) — certified artifact + provenance (corpus hash, engine version, gate numbers) as a CBOR-framed sidecar, so the engine can refuse uncertified artifacts.

Native-only: the pipeline drives the real inference stack (GGUF, GPU, PPL oracle).

Re-exports

pub use crate::kv_dict_runtime;

pub use corpus::CorpusSpec;

pub use kv_dictionary::learn_dictionary;

pub use kv_dictionary::KvDictionary;

pub use kv_dictionary::SparseCode;

pub use package::Provenance;

Modules

corpus

W10 calibration — stage 1: corpus assembly.

kv_dictionary

W5b — the sparse KV-dictionary learner (the forge/training step) + its rate-distortion metrics.

package

W10 calibration — stage 5: provenance + packaging.

Structs

CalibrationJob

A calibration job: produce artifact for model_path, calibrated on corpus, gated by gate.

CalibrationReport

The outcome of a calibration run.

GateSpec

The ΔPPL acceptance gate for a lossy artifact (fraction, e.g. 0.05 = 5%).

KvDictReport

The W5b Phase-3 decision: does a learned sparse dictionary beat int8 on the engine’s real KV vectors? Per-layer detail plus an overall verdict.

KvLayerVerdict

Per-(layer, stream) rate-distortion comparison. int8 (the W5a incumbent, 8 bits/elem) is a strong, accurate baseline; a sparse dictionary trades accuracy for a much smaller footprint. So the decision isn’t “does the dictionary beat int8’s accuracy” (it won’t — int8 has ~4× the bits) but “at the dictionary’s OWN low bit rate, does the learned basis beat NAIVE uniform quantization?” — i.e. is the learned codebook worth more than just quantizing more coarsely.

Enums

ArtifactKind

Which calibration artifact to produce.

CalibrationError

Functions

certify_kv_dictionary

Single-config convenience wrapper over sweep_kv_dictionary.

kv_dictionary_go_no_go

W5b Phase 3 — the sparse-KV-dictionary go/no-go on real engine KV vectors.

kv_dictionary_go_no_go_gpu

W5b Phase 3 — the same go/no-go via the GPU-readback capture route ([crate::llm_bench:: capture_kv_gpu_readback]): reads the real fast-decode-path K/V straight from VRAM instead of forcing the CPU reference SDPA. Running this alongside kv_dictionary_go_no_go cross-checks the measured geometry — if the two routes agree, the verdict is trustworthy.

run_calibration

Run the calibration pipeline for one job. The forge’s third produce-and-certify entry point, beside kernel certification and GGUF→p64 transcode.

sweep_kv_dictionary

W5b Phase 4 — certify one or more KV-dictionary configs by ΔPPL, sharing the expensive capture + reference-PPL across all of them.