IMPLEMENTATION_REFERENCES.md

Implementation references

TurboFieldfare builds on work by other developers and researchers. These are the sources that materially shaped its Gemma 4 implementation, Metal kernels, out-of-core runtime, and experiments under the 8 GB memory constraint.

Upstream code references whose exact behavior mattered are pinned to commits checked on 2026-07-16. Project home pages remain branch-level when they are included for broader design context rather than a line-level claim.

Model and weights

• The official Gemma 4 model card defines the model family, the 26B A4B mixture-of-experts shape, hybrid attention, and intended capabilities.
• Hugging Face Transformers provides executable decoder cross-checks for Gemma 4 math, configuration, and RoPE utilities. TurboFieldfare used them to verify normalization, K/V derivation, routing, MoE combination, layer scaling, and final logits.
• MLX-LM Gemma 4 and MLX-VLM Gemma 4 supplied independent implementation checks. MLX-LM also served as the bounded logit and quality reference.
• mlx-community/gemma-4-26b-a4b-it-4bit, pinned at 0d77464e, is the source of the weights, configuration, tokenizer, and chat-template sidecars. The repacker preserves its group-64 MLX affine values rather than requantizing them.
• Hugging Face swift-transformers is the direct tokenizer dependency. TurboFieldfare adds bounded streaming detokenization around it.

Metal and kernels

• Pinned MLX Metal kernels were the main reference for quantized QMV/QMM, RMSNorm, RoPE, and attention geometry. The tagged v0.32.0 vector SDPA inspired the D512 one-pass attention variant.
• Pinned llama.cpp/ggml Metal informed row-SIMD quantized matvec, register-resident decode, capability-gated kernels, memory mappings, and resource hazards.
• LeetCUDA supplied transferable patterns for SIMD-per-row GEMV, packed loads, reductions, online softmax, and split-KV attention.

Apple platform contracts

• Apple's Metal Performance Primitives guide and Metal tensor session define the platform contract for MTLTensor, cooperative inputs, mpp::tensor_ops::matmul2d, execution scopes, data types, and alignment. They guided the staged affine MPP prefill path.

Apple shader operations

• Apple's inline Metal 4 operations documents shader-local tensors and inline cooperative operations considered in the Metal 4 experiments.

Out-of-core inference

• danveloper/flash-moe, Anemll/flash-moe, and SwiftLM informed Apple-Silicon SSD-backed MoE, positional reads, reusable expert buffers, I/O workers, and GPU synchronization.
• Apple's LLM in a Flash framed the out-of-core problem around transferred bytes, useful read size, and flash scheduling.
• Apple's Darwin pread(2), mmap(2), and fcntl(2) document concurrent offset reads, page alignment, and file-advice APIs such as F_RDADVISE.

KV-cache and attention research

• FlashAttention, online normalizer calculation, and Flash-Decoding supplied the tiled-attention and associative online-softmax principles behind TurboFieldfare's split-KV kernels.
• Pinned vLLM attention operators and vLLM Metal kernels v2 were implementation references for transformed and quantized KV caches, fused dequantization, and online-softmax reduction.
• TurboQuant and Open-TQ-Metal informed the rejected K4/V4 KV-cache experiments.