docs(kolibri1): land the third-oracle artifacts and the orphaned records

.agents/issues/MODEL-TEXT-kolibri-1-kolibri1-for-causal-lm/ISSUE-LOCAL-01M4R8DVBMQA4WWCF9X6VG00E1.md

@@ -0,0 +1,19 @@
+ID: ISSUE-LOCAL-01M4R8DVBMQA4WWCF9X6VG00E1
+Title: Kolibri1 CPU decode GEMV stage: attribute math vs dispatch/sync overhead at t32 and price the batching restructures
+Row: MODEL-TEXT-kolibri-1-kolibri1-for-causal-lm
+State: OPEN
+Kind: gap
+GitHub: -
+Mirror: PENDING
+Availability: FULL
+Created: 2026-10-12
+Updated: 2026-10-12
+Closed: -
+
+## Problem
+
+Production kolibri decode at t32+32GiB cache+NEON runs 175 ms/step while the linear GEMV stage aggregates only ~3.1 Gelem/s across 32 threads vs 10.5 Gelem/s single-thread (vbfdotq micro). The step looks serialization-dominated (pool kicks, per-call sync), not arithmetic- or bandwidth-bound. No per-GEMV-site attribution of math vs dispatch exists, and the candidate restructures (batch 6-expert GEMVs, batch q/k/v, eliminate per-call sync) are unpriced.
+
+## Resolution
+
+-

scripts/aleph-alpha-inference-smoke.py

@@ -0,0 +1,51 @@
+#!/usr/bin/env python3
+"""Smoke test: can vLLM's CPU backend serve Kolibri-1 via the author's own plugin?
+
+The question is whether the primary oracle is reachable without a GPU lease. It registers
+and imports; this checks that it executes. One short prompt, one token, eager mode, minimal
+context - the smallest thing that would still exercise the MoE forward.
+"""
+import os
+import sys
+import time
+
+MODEL = "/mnt/models/Aleph-Alpha/Kolibri-1-bf16-clean"
+
+os.environ.setdefault("VLLM_LOGGING_LEVEL", "INFO")
+os.environ.setdefault("VLLM_PLUGINS", "aleph_alpha_inference")
+os.environ.setdefault("TOKENIZERS_PARALLELISM", "false")
+
+from vllm import LLM, SamplingParams  # noqa: E402
+
+
+def main():
+    t0 = time.perf_counter()
+    llm = LLM(
+        model=MODEL,
+        tokenizer=MODEL,
+
+
+        max_model_len=64,
+        max_num_seqs=1,
+        gpu_memory_utilization=0.74,
+        tensor_parallel_size=4,
+        distributed_executor_backend="mp",
+        enforce_eager=True,
+        disable_log_stats=True,
+        trust_remote_code=True,
+    )
+    print(f"[smoke] model loaded in {time.perf_counter()-t0:.1f}s", flush=True)
+
+    prompts = ["The capital of Australia is"]
+    t1 = time.perf_counter()
+    out = llm.generate(prompts, SamplingParams(temperature=0.0, max_tokens=8))
+    dt = time.perf_counter() - t1
+    for o in out:
+        print(f"[smoke] prompt {o.prompt!r} -> {o.outputs[0].text!r}")
+        print(f"[smoke] token ids: {list(o.outputs[0].token_ids)}")
+    print(f"[smoke] 8 tokens in {dt:.1f}s ({8/dt:.3f} tok/s)", flush=True)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scripts/compare-kolibri1-oracles.py

@@ -0,0 +1,118 @@
+"""Compare the Kolibri-1 oracles position by position, with the lag auto-detected.
+
+The primary's rows were written one position ahead (rows[k+1] holds the distribution for
+step k). That offset is detected here rather than assumed, so this works on the old file
+and on a repaired one without changes.
+
+Usage:
+    python3 compare-kolibri1-oracles.py [primary_rows.json] [llamacpp_rows.json]
+
+Both files are expected in the primary's topk-rows format: prompts[] with
+{input_ids, generated_ids, rows:[{gen_index, token, top:[[id,logprob]], logprob_of_token,
+top1_top2_margin, top6_top7_margin}]}.
+"""
+
+import json
+import sys
+
+HERE = "tests/vllm/models/"
+PRIMARY = sys.argv[1] if len(sys.argv) > 1 else HERE + "kolibri1_primary_topk_rows.json"
+LLAMA = sys.argv[2] if len(sys.argv) > 2 else HERE + "kolibri1_llamacpp_topk_rows.json"
+
+
+def load(p):
+    d = json.load(open(p))
+    pr = d["prompts"]
+    pr = list(pr.values()) if isinstance(pr, dict) else pr
+    out = []
+    for e in pr:
+        rows = e["rows"]
+        if isinstance(rows, dict):
+            rows = {int(k): v for k, v in rows.items()}
+        else:
+            rows = {r["gen_index"]: r for r in rows}
+        out.append((e, rows))
+    return out
+
+
+def detect_shift(primary, llama):
+    """Which offset makes the primary's chain its own rows' argmax?"""
+    best_rate, best_shift = -1.0, 0
+    for shift in (0, 1, -1, 2, -2):
+        hits = tot = 0
+        for (pe, prows), (le, lrows) in zip(primary, llama):
+            for k, tok in enumerate(pe["generated_ids"]):
+                rk = k + shift
+                if rk not in prows or rk not in lrows:
+                    continue
+                top = prows[rk]["top"]
+                if not top:
+                    continue
+                tot += 1
+                if top[0][0] == tok:
+                    hits += 1
+        rate = hits / tot if tot else 0.0
+        print(f"  shift {shift:+d}: {hits}/{tot} = {rate*100:.1f}%")
+        if rate > best_rate:
+            best_rate, best_shift = rate, shift
+    return best_shift, best_rate
+
+
+def main():
+    primary, llama = load(PRIMARY), load(LLAMA)
+    shift, rate = detect_shift(primary, llama)
+    print(f"primary: {PRIMARY}")
+    print(f"llama  : {LLAMA}")
+    print(f"detected primary row offset: {shift:+d}  (chain-matches-own-argmax {rate*100:.1f}%)")
+    print()
+
+    n = len(primary)
+    ft = {"p vs l": 0, "p vs t": 0}
+    seq = {"p vs l": 0, "p vs t": 0}
+    d_all = []
+    margins_dis = []
+    for i, ((pe, prows), (le, lrows)) in enumerate(zip(primary, llama)):
+        pg, lg = pe["generated_ids"], le["generated_ids"]
+        if pg and lg:
+            if pg[0] == lg[0]:
+                ft["p vs l"] += 1
+            if pg == lg:
+                seq["p vs l"] += 1
+        cp = 0
+        for a, b in zip(pg, lg):
+            if a != b:
+                break
+            cp += 1
+        for k in range(cp):
+            rk, lk = k + shift, k
+            if rk not in prows or lk not in lrows:
+                continue
+            ptop = dict((int(t), float(v)) for t, v in prows[rk]["top"])
+            ltop = dict((int(t), float(v)) for t, v in lrows[lk]["top"])
+            if not ptop or not ltop:
+                continue
+            shared = set(ptop) & set(ltop)
+            if shared:
+                d_all.append(max(abs(ptop[s] - ltop[s]) for s in shared))
+            if list(ptop)[0] != list(ltop)[0]:
+                margins_dis.append(prows[rk].get("top1_top2_margin"))
+    d_all.sort()
+    print(f"first token agrees: {ft['p vs l']}/{n}    identical full sequence: {seq['p vs l']}/{n}")
+    if d_all:
+        print(
+            f"max |dlogprob| on shared tokens, common prefix only (n={len(d_all)}): "
+            f"median={d_all[len(d_all)//2]:.4f} p90={d_all[int(0.9*len(d_all))]:.4f} max={d_all[-1]:.4f} nats"
+        )
+    if margins_dis:
+        margins_dis.sort()
+        print(
+            f"argmax disagreements on the common prefix: {len(margins_dis)}, "
+            f"primary top1/top2 margin at those positions: "
+            f"median={margins_dis[len(margins_dis)//2]:.4f} min={margins_dis[0]:.4f}"
+        )
+    else:
+        print("argmax disagreements on the common prefix: 0")
+
+
+if __name__ == "__main__":
+    main()

scripts/gen-kolibri1-primary-goldens.py

@@ -0,0 +1,112 @@
+#!/usr/bin/env python3
+"""Generate Kolibri-1 goldens from the PRIMARY oracle.
+
+The existing goldens come from a pure-torch transcription of the plugin's math. This runs the
+plugin itself, through vLLM, at the pinned commit - so the fingerprints are the model author's
+own implementation rather than a proxy for it.
+
+Same shape as tests/vllm/models/kolibri1_goldens.json: greedy, temperature 0, 32 tokens, the
+8-prompt set, so the two files can be diffed directly.
+
+Slow by design: 0.6 tok/s. It runs once, offline. Speed is irrelevant to a fingerprint.
+"""
+import json
+import os
+import sys
+
+MODEL = "/mnt/models/Aleph-Alpha/Kolibri-1-bf16-clean"
+OUT = sys.argv[1] if len(sys.argv) > 1 else "/tmp/opencode/kolibri1_goldens_primary.json"
+
+MAX_NEW_TOKENS = 32
+
+PROMPTS = [
+    "alpha beta gamma delta epsilon zeta",
+    "der Mond scheint hell über den Bergen",
+    "The capital of Australia is",
+    "Wissen ist Macht, aber Zeit ist Geld",
+    "x1 = 3, x2 = 7, x3 = 11, x4 =",
+    "Translation to German: the weather is beautiful today",
+    "Ein gutes Buch liest man am besten",
+    "counting: one two three four five six seven",
+]
+
+os.environ.setdefault("VLLM_PLUGINS", "aleph_alpha_inference")
+os.environ.setdefault("TOKENIZERS_PARALLELISM", "false")
+
+from transformers import AutoTokenizer  # noqa: E402
+from vllm import LLM, SamplingParams  # noqa: E402
+
+
+def main() -> int:
+    tok = AutoTokenizer.from_pretrained(MODEL)
+    llm = LLM(
+        model=MODEL,
+        tokenizer=MODEL,
+        dtype="bfloat16",
+        max_model_len=512,
+        max_num_seqs=1,
+        gpu_memory_utilization=0.74,
+        tensor_parallel_size=4,
+        distributed_executor_backend="mp",
+        enforce_eager=True,
+        disable_log_stats=True,
+        trust_remote_code=True,
+    )
+    params = SamplingParams(temperature=0.0, max_tokens=MAX_NEW_TOKENS, logprobs=8)
+
+    entries = []
+    for i, prompt in enumerate(PROMPTS):
+        ids = tok.encode(prompt, add_special_tokens=False)
+        out = llm.generate([prompt], params, use_tqdm=False)[0]
+        gen = list(out.outputs[0].token_ids)
+        # Final-position top-8, as logprobs: vLLM does not surface raw logits.
+        final = {}
+        if out.outputs[0].logprobs:
+            last = out.outputs[0].logprobs[-1]
+            final = {
+                "top8_token_ids": [t for t, _ in sorted(last.items(), key=lambda kv: -kv[1].logprob)],
+                "top8_logprobs": [
+                    round(float(v.logprob), 4)
+                    for _, v in sorted(last.items(), key=lambda kv: -kv[1].logprob)
+                ],
+            }
+        entries.append({
+            "prompt": prompt,
+            "input_ids": ids,
+            "generated_ids": gen,
+            "final_topk": final,
+        })
+        print(f"[{i+1}/{len(PROMPTS)}] {prompt!r}: argmax-first {gen[0] if gen else None}, "
+              f"{len(gen)} tokens", flush=True)
+
+    old = json.load(open(
+        "/home/lu_zero/Sources/vllm.cpp/tests/vllm/models/kolibri1_goldens.json"))
+    agree = sum(
+        1 for a, b in zip(entries, old["prompts"]) if a["generated_ids"] == b["generated_ids"]
+    )
+    first = sum(1 for a, b in zip(entries, old["prompts"]) if a["generated_ids"][:1] == b["generated_ids"][:1])
+
+    out = {
+        "model": MODEL,
+        "max_new_tokens": MAX_NEW_TOKENS,
+        "decode": "greedy, temperature 0",
+        "provenance": "PRIMARY oracle: aleph-alpha-inference 1.0.0 (049a6a7) via vLLM "
+                      f"{__import__('vllm').__version__} CPU, tensor_parallel_size=4",
+        "vs_transcription_goldens": {
+            "identical_full_sequences": f"{agree}/{len(PROMPTS)}",
+            "identical_first_token": f"{first}/{len(PROMPTS)}",
+        },
+        "prompts": entries,
+    }
+    with open(OUT, "w") as f:
+        json.dump(out, f, indent=1)
+        f.write("\n")
+    print(f"\nidentical full sequences vs the transcription goldens: "
+          f"{agree}/{len(PROMPTS)}")
+    print(f"identical first token: {first}/{len(PROMPTS)}")
+    print(f"wrote {OUT}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())