fix(tq): default --tq-mode to auto — KVarN where supported, Lloyd-Max fallback with quality warning (#432)

[pekkah]

Problem

--tq (Lloyd-Max 3-bit, the default TurboQuant codec) collapses on Qwen3: wikitext-2 PPL 945.6 vs 15.47 fp32 at c=3072, and 19/20 math-eval generations degenerate into token loops (#432).

Root cause

Three probes, all on real Qwen3-0.6B K/V vectors captured from the live forward pass (full analysis in #432 comment):

1. Not the Hadamard sign-flip ordering. TurboQuantOps applies the sign flip after the WHT, which is mathematically a bare un-randomized WHT — but an A/B on real K/V shows identical reconstruction error for both orderings (relErr ≈ 0.18).
2. Not a read-path bug. The FastScan tile/LUT machinery tracks the per-block DequantDot/Decompress reference to ~1% of the quantizer's own error.
3. Intrinsic 3-bit distortion × Qwen3's logit scale. ~7% relative K-score error meets QK-norm attention logits with RMS ≈ 1000 → absolute logit errors of tens of units → softmax destroyed. 4-bit Lloyd-Max measures PPL 51.8 — better, still unusable. KVarN measures 15.67.

Fix

Make the validated KVarN codec the default wherever it is supported, per the issue's own recommendation:

• CLI (run + perplexity): --tq-mode defaults to auto → KVarN on CPU (any pow-2 head dim in [8, 1024]) and full-CUDA-offload dense (head dim ≤ 256); falls back to Lloyd-Max with a loud quality warning citing TurboQuant Lloyd-Max 3-bit collapses on Qwen3 (PPL 61x, degenerate decode) — pre-existing on master #432 on Vulkan, partial CUDA offload, MoE-on-GPU, SnapKV, or window < 128. Explicit --tq-mode lloydmax keeps the old behavior and silences the warning; explicit kvarn still errors on unsupported combos.
• Server: new TqMode option (default auto) with the same per-path resolution in InferenceEngineLoader (explicit kvarn on an unsupported path fails model load); SHARPI_TQ / SHARPI_TQ_MODE env vars in the Host.
• Docs: flag descriptions, CLI README, and quality warnings on TqQuantizer.LloydMax / ForwardPass.EnableTurboQuant XML docs.

Validation

• Default --tq on the issue's exact gate now runs tq-kvarn-k4v2 at PPL 15.6741 (was 945.56); explicit --tq-mode lloydmax reproduces the old numbers.
• SHARPI_SNAPKV_BUDGET + --tq prints the Lloyd-Max fallback warning and runs.
• run --tq -g -1 on CUDA resolves to KVarN K4V2.
• Solution builds clean (warnings-as-errors); Tests.Cli 93/93, Tests.Server 154/154 (new tests cover the auto-resolution matrix).

Follow-up

The GPU Lloyd-Max TqAttention V-basis defect found during this audit (compressed-region V aggregate never un-rotated on CUDA/Vulkan) is tracked separately as #435.

Closes #432

🤖 Generated with Claude Code

https://claude.ai/code/session_01EuBdnPNJ2XdaFp9PjYoJyz

[gemini-code-assist]

Code Review

This pull request introduces an "auto" mode for the TurboQuant KV cache compression quantizer, which automatically selects the higher-quality KVarN quantizer where supported and falls back to Lloyd-Max with a warning on unsupported configurations. It also adds environment variable support for these options in the server host and updates the CLI commands, documentation, and tests. The review feedback highlights two important issues in the server's InferenceEngineLoader: first, an early head-dimension check unconditionally blocks KVarN for head dimensions other than 128 or 256; second, the CUDA path lacks a check to fall back to Lloyd-Max when the head dimension exceeds 256.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

The current head dimension check is executed before tqQuantizer and tqModeIsAuto are resolved, and it unconditionally rejects any head dimension other than 128 or 256 when turboQuant is enabled. This prevents loading models with other power-of-2 head dimensions (such as 64, 512, or 1024) when using KVarN on the server, even though KVarN supports them. Moving the check after the switch statement and validating based on the resolved quantizer fixes this issue.

        bool tqModeIsAuto = false;
        TqQuantizer tqQuantizer;
        switch ((opts.TqMode ?? "auto").Trim().ToLowerInvariant())
        {
            case "" or "auto":
                tqModeIsAuto = true;
                tqQuantizer = TqQuantizer.LloydMax; // resolved per-path in BuildForwardPass
                break;
            case "lloydmax" or "lloyd-max":
                tqQuantizer = TqQuantizer.LloydMax;
                break;
            case "kvarn":
                tqQuantizer = TqQuantizer.KVarN;
                break;
            default:
                throw new InvalidOperationException(
                    $"Unknown TqMode '{opts.TqMode}'. Expected one of: auto, lloydmax, kvarn.");
        }

        if (turboQuant)
        {
            bool isKVarN = tqModeIsAuto || tqQuantizer == TqQuantizer.KVarN;
            if (isKVarN)
            {
                bool headDimOk = hp.HeadDim >= 8 && hp.HeadDim <= 1024 && (hp.HeadDim & (hp.HeadDim - 1)) == 0;
                if (!headDimOk)
                    throw new InvalidOperationException(
                        $"TurboQuant KVarN requires a power-of-2 head dimension in [8, 1024]; this model has head dim {hp.HeadDim}.");
            }
            else if (hp.HeadDim is not 128 and not 256)
            {
                throw new InvalidOperationException(
                    $"TurboQuant Lloyd-Max requires head dimension 128 or 256; this model has head dim {hp.HeadDim}.");
            }
        }

[gemini-code-assist]

When resolving the quantizer for CudaForwardPass, we should check if the head dimension exceeds 256 on CUDA. If it does, we should block KVarN and fall back to Lloyd-Max (with a warning in auto mode) instead of potentially failing to load the model later.

                    tqQuantizer: ResolveTq(hp.IsMoE ? "KVarN on CUDA supports dense models only" : hp.HeadDim > 256 ? $"KVarN on CUDA requires head dim ≤ 256; this model has {hp.HeadDim}" : null),

[pekkah]

Code review (high effort, 8 finder angles + verify)

Ran an 8-angle multi-agent review (line-by-line, removed-behavior, cross-file, reuse, simplification, efficiency, altitude, conventions). One real regression this PR introduced, fixed in 80c1445; the rest are pre-existing or tech-debt, filed as follow-ups.

Fixed (80c1445)

• CONFIRMED regression — partial-offload crash. A dense model with a pow-2 head dim outside {128,256} (e.g. 64) run with --tq -g -1 on a GPU too small for full offload resolved auto→KVarN (passes the pow-2 gate), skipped the Lloyd-Max 128/256 gate, then the wantHybrid branch downgraded to Lloyd-Max without re-checking → new CudaHybridForwardPass(turboQuant:true) throws an uncaught NotSupportedException (CudaHybridForwardPass.cs:386) instead of the clean CLI error explicit --tq-mode lloydmax gives. Pre-PR this model errored cleanly at the 128/256 gate. Now guarded: the downgrade rejects non-{128,256} head dims with an actionable "use -g 0 for CPU KVarN" message.
• Cleanup: dropped a dead KVarN K4V2 message branch in the Vulkan CPU-fallback (KVarN can never reach the Vulkan backend — explicit is rejected, auto falls back to Lloyd-Max). Updated the stale TurboQuant description in CLAUDE.md.

Follow-ups (not blocking — pre-existing or tech-debt)

• Server head-dim gate (InferenceEngineLoader.cs:85) rejects every head dim ∉{128,256} whenever TQ is on, before quantizer resolution — so KVarN's broader head-dim support (32/64/512/1024) is unreachable on the server, and explicit TqMode=kvarn on such a model gets a misleading "128 or 256" error. Not a regression (head-dim-64+TQ never worked on the server's Lloyd-Max-only path), but the CLI now runs it. Worth extending the server to match.
• Triplicated support matrix. The KVarN-support rules (SnapKV / head dim / backend / offload / MoE) and the TurboQuant Lloyd-Max 3-bit collapses on Qwen3 (PPL 61x, degenerate decode) — pre-existing on master #432 warning text are hand-copied across RunCommand, PerplexityCommand.ResolveAutoQuantizer, and InferenceEngineLoader.ResolveTq with duplicated reason strings. The crash above was a direct symptom of one copy drifting. A single Engine-level TqSupport.ResolveAuto(...) next to TqQuantizer (only the perplexity copy is unit-tested today) would prevent recurrence.
• SnapKV + Lloyd-Max on CUDA full-offload prints a "falling back to Lloyd-Max (SnapKV…)" warning before an unavoidable throw — the fallback reason is only valid on CPU (where Lloyd-Max+SnapKV works); on CUDA neither codec composes with SnapKV. Cosmetic; the actionable throw survives.
• Server silently ignores TqMode=kvarn when TurboQuant=false (CLI rejects the same combo). Minor.

I'll open a tracking issue for the matrix centralization + server head-dim extension.