eigencore 0.4.0__py3-none-any.whl

eigencore/hal/profiler.py

@@ -0,0 +1,349 @@
+"""
+Hardware Abstraction Layer — auto-detects CPU capabilities, RAM, and memory bandwidth
+to determine optimal model configuration without manual user input.
+"""
+
+from __future__ import annotations
+
+import platform
+import time
+from dataclasses import dataclass, field
+from enum import Flag, auto
+
+import psutil
+
+
+class InstructionSet(Flag):
+    NONE = 0
+    SSE2 = auto()
+    SSE4_1 = auto()
+    SSE4_2 = auto()
+    AVX = auto()
+    AVX2 = auto()
+    AVX512F = auto()
+    AVX512BW = auto()
+    AVX512VNNI = auto()
+    FMA = auto()
+    F16C = auto()
+    AMX_TILE = auto()
+    AMX_INT8 = auto()
+    AMX_BF16 = auto()
+    NEON = auto()
+    SVE = auto()
+
+
+@dataclass(frozen=True)
+class HardwareProfile:
+    cpu_name: str
+    arch: str
+    physical_cores: int
+    logical_cores: int
+    instruction_sets: InstructionSet
+    total_ram_gb: float
+    available_ram_gb: float
+    estimated_bandwidth_gbps: float
+    max_model_params_b: float
+    optimal_quantization: str
+    estimated_tokens_per_sec: float
+    recommended_threads: int
+    recommended_context_length: int
+    gpu_name: str | None = None
+    total_vram_gb: float = 0.0  # 0 = no GPU / unknown
+    available_vram_gb: float = 0.0
+    notes: list[str] = field(default_factory=list)
+
+    def summary(self) -> str:
+        isa_names = [
+            f.name for f in InstructionSet if f in self.instruction_sets and f.name != "NONE"
+        ]
+        lines = [
+            f"CPU: {self.cpu_name} ({self.arch})",
+            f"Cores: {self.physical_cores}P / {self.logical_cores}L",
+            f"ISA: {', '.join(isa_names) if isa_names else 'baseline'}",
+            f"RAM: {self.available_ram_gb:.1f} / {self.total_ram_gb:.1f} GB available",
+            f"Bandwidth: ~{self.estimated_bandwidth_gbps:.1f} GB/s",
+            (
+                f"GPU: {self.gpu_name} | VRAM: {self.available_vram_gb:.1f} / {self.total_vram_gb:.1f} GB available"
+                if self.gpu_name
+                else "GPU: none detected (CPU-only mode)"
+            ),
+            "",
+            f"Max model: ~{self.max_model_params_b:.1f}B params at {self.optimal_quantization}",
+            f"Est. speed: ~{self.estimated_tokens_per_sec:.0f} tok/s",
+            f"Threads: {self.recommended_threads}",
+            f"Context: {self.recommended_context_length} tokens",
+        ]
+        if self.notes:
+            lines.append("")
+            for note in self.notes:
+                lines.append(f"  * {note}")
+        return "\n".join(lines)
+
+
+def _detect_instruction_sets_x86() -> InstructionSet:
+    """Detect x86 SIMD capabilities via CPUID."""
+    isa = InstructionSet.NONE
+
+    if platform.system() == "Windows":
+        try:
+            from eigencore.hal._cpuid_win import detect_isa_windows
+
+            return detect_isa_windows()
+        except ImportError:
+            pass
+
+    try:
+        with open("/proc/cpuinfo", "r") as f:
+            cpuinfo = f.read().lower()
+
+        flag_map = {
+            "sse2": InstructionSet.SSE2,
+            "sse4_1": InstructionSet.SSE4_1,
+            "sse4_2": InstructionSet.SSE4_2,
+            "avx": InstructionSet.AVX,
+            "avx2": InstructionSet.AVX2,
+            "avx512f": InstructionSet.AVX512F,
+            "avx512bw": InstructionSet.AVX512BW,
+            "avx512_vnni": InstructionSet.AVX512VNNI,
+            "fma": InstructionSet.FMA,
+            "f16c": InstructionSet.F16C,
+            "amx_tile": InstructionSet.AMX_TILE,
+            "amx_int8": InstructionSet.AMX_INT8,
+            "amx_bf16": InstructionSet.AMX_BF16,
+        }
+        for flag, isa_val in flag_map.items():
+            if flag in cpuinfo:
+                isa |= isa_val
+    except FileNotFoundError:
+        pass
+
+    return isa
+
+
+def _detect_instruction_sets_arm() -> InstructionSet:
+    """Detect ARM SIMD capabilities."""
+    isa = InstructionSet.NONE
+
+    if platform.machine().lower() in ("aarch64", "arm64"):
+        isa |= InstructionSet.NEON
+
+    try:
+        with open("/proc/cpuinfo", "r") as f:
+            cpuinfo = f.read().lower()
+        if "sve" in cpuinfo:
+            isa |= InstructionSet.SVE
+    except FileNotFoundError:
+        pass
+
+    return isa
+
+
+def _measure_bandwidth() -> float:
+    """Estimate memory bandwidth via timed memcpy benchmark (GB/s)."""
+    try:
+        block_size = 64 * 1024 * 1024  # 64 MB
+        src = bytearray(block_size)
+        iterations = 5
+
+        # warmup
+        _ = bytes(src)
+
+        times = []
+        for _ in range(iterations):
+            start = time.perf_counter()
+            _ = bytearray(src)
+            elapsed = time.perf_counter() - start
+            times.append(elapsed)
+
+        median_time = sorted(times)[len(times) // 2]
+        bandwidth_gbps = (block_size / (1024**3)) / median_time
+        # memcpy measures roughly half of peak bandwidth (read + write)
+        return bandwidth_gbps * 2
+    except Exception:
+        return 20.0  # conservative fallback
+
+
+def _get_cpu_name() -> str:
+    """Get human-readable CPU name."""
+    if platform.system() == "Windows":
+        try:
+            import winreg
+
+            key = winreg.OpenKey(
+                winreg.HKEY_LOCAL_MACHINE,
+                r"HARDWARE\DESCRIPTION\System\CentralProcessor\0",
+            )
+            name, _ = winreg.QueryValueEx(key, "ProcessorNameString")
+            winreg.CloseKey(key)
+            return name.strip()
+        except Exception:
+            pass
+
+    try:
+        with open("/proc/cpuinfo", "r") as f:
+            for line in f:
+                if "model name" in line.lower():
+                    return line.split(":")[1].strip()
+    except FileNotFoundError:
+        pass
+
+    return platform.processor() or "Unknown CPU"
+
+
+def _compute_model_limits(
+    available_ram_gb: float,
+    bandwidth_gbps: float,
+) -> tuple[float, str, float, int, int]:
+    """
+    Given available RAM and bandwidth, compute:
+    - max model size in billions of parameters
+    - optimal quantization level
+    - estimated tokens per second
+    - recommended thread count
+    - recommended context length
+
+    All sizes in GiB (1 GiB = 1024**3 bytes) end to end.
+    We reserve 2 GiB for OS/runtime overhead plus a KV-cache share, then fit
+    the largest model possible.
+    """
+    usable_ram_gib = max(available_ram_gb - 2.0, 1.0)
+
+    quant_options = [
+        ("Q4_K_M", 0.55),  # ~0.55 bytes per param (4-bit with some FP16 layers)
+        ("Q5_K_M", 0.68),  # ~0.68 bytes per param
+        ("Q8_0", 1.05),  # ~1.05 bytes per param
+        ("F16", 2.0),  # 2 bytes per param
+    ]
+
+    best_params_b = 0.0
+    best_quant = "Q4_K_M"
+
+    for quant_name, bytes_per_param in quant_options:
+        max_params = (usable_ram_gib * 1024**3) / (bytes_per_param * 1e9)
+        if max_params > best_params_b:
+            best_params_b = max_params
+            best_quant = quant_name
+
+    # cap at realistic model sizes available in GGUF
+    best_params_b = min(best_params_b, 70.0)
+
+    # estimate tokens/sec: bandwidth / model_size_in_memory (ceiling estimate)
+    model_size_gib = best_params_b * 0.55  # assuming best quant (Q4)
+    if model_size_gib > 0:
+        est_tps = bandwidth_gbps / model_size_gib
+        est_tps = min(est_tps, 100.0)  # cap at reasonable maximum
+    else:
+        est_tps = 0.0
+
+    # recommended threads: physical cores (hyperthreads don't help much for inference)
+    recommended_threads = psutil.cpu_count(logical=False) or 4
+
+    # context length: RAM left after model, reserving 25% of usable RAM for
+    # the KV cache so the recommendation does not collapse to the 2048 floor
+    # on machines under ~38 GiB.
+    kv_budget_gib = 0.25 * usable_ram_gib
+    remaining_gib = usable_ram_gib - model_size_gib - kv_budget_gib
+    if best_params_b > 0 and remaining_gib > 0:
+        # pessimistic geometry-free KV rate: ~2 MB per 1K tokens per 1B params (fp16)
+        kv_per_1k = 0.002 * best_params_b  # GiB per 1K tokens
+        max_ctx = int((remaining_gib / kv_per_1k) * 1000) if kv_per_1k > 0 else 2048
+        recommended_ctx = min(max_ctx, 8192)  # cap at 8K for CPU
+        recommended_ctx = max(recommended_ctx, 512)  # minimum usable
+    else:
+        recommended_ctx = 2048
+
+    return best_params_b, best_quant, est_tps, recommended_threads, recommended_ctx
+
+
+def profile_hardware() -> HardwareProfile:
+    """Run full hardware profiling and return a HardwareProfile with recommendations."""
+    arch = platform.machine().lower()
+    is_arm = arch in ("aarch64", "arm64")
+    is_x86 = arch in ("x86_64", "amd64", "x86")
+
+    cpu_name = _get_cpu_name()
+
+    if is_x86:
+        isa = _detect_instruction_sets_x86()
+    elif is_arm:
+        isa = _detect_instruction_sets_arm()
+    else:
+        isa = InstructionSet.NONE
+
+    mem = psutil.virtual_memory()
+    gpu_name, total_vram_gb, available_vram_gb = _detect_gpu()
+    total_ram_gb = mem.total / (1024**3)
+    available_ram_gb = mem.available / (1024**3)
+
+    bandwidth = _measure_bandwidth()
+
+    max_params, quant, est_tps, threads, ctx = _compute_model_limits(available_ram_gb, bandwidth)
+
+    notes = []
+    if not is_x86 and not is_arm:
+        notes.append(f"Unrecognized architecture: {arch}. Using conservative defaults.")
+    if InstructionSet.AVX2 not in isa and is_x86:
+        notes.append("No AVX2 detected — inference will be significantly slower.")
+    if available_ram_gb < 4.0:
+        notes.append("Very low available RAM. Close other applications for better performance.")
+    if InstructionSet.AVX512F in isa:
+        notes.append("AVX-512 detected — llama.cpp will use optimized 512-bit kernels.")
+    if InstructionSet.AMX_INT8 in isa:
+        notes.append("AMX detected — hardware matrix acceleration available.")
+
+    return HardwareProfile(
+        cpu_name=cpu_name,
+        arch=arch,
+        physical_cores=psutil.cpu_count(logical=False) or 1,
+        logical_cores=psutil.cpu_count(logical=True) or 1,
+        instruction_sets=isa,
+        total_ram_gb=total_ram_gb,
+        available_ram_gb=available_ram_gb,
+        estimated_bandwidth_gbps=bandwidth,
+        max_model_params_b=max_params,
+        optimal_quantization=quant,
+        estimated_tokens_per_sec=est_tps,
+        recommended_threads=threads,
+        recommended_context_length=ctx,
+        gpu_name=gpu_name,
+        total_vram_gb=total_vram_gb,
+        available_vram_gb=available_vram_gb,
+        notes=notes,
+    )
+
+
+def _detect_gpu() -> tuple[str | None, float, float]:
+    """Best-effort GPU/VRAM detection.
+
+    Tries NVIDIA via `nvidia-smi` (name + memory), else returns no GPU.
+    Never raises; unknown hardware just yields zeros and a note.
+    """
+    import shutil
+    import subprocess
+
+    if not shutil.which("nvidia-smi"):
+        return None, 0.0, 0.0
+    try:
+        out = (
+            subprocess.run(
+                [
+                    "nvidia-smi",
+                    "--query-gpu=name,memory.total,memory.used",
+                    "--format=csv,noheader,nounits",
+                ],
+                capture_output=True,
+                text=True,
+                timeout=5,
+                check=True,
+            )
+            .stdout.strip()
+            .splitlines()
+        )
+        if not out:
+            return None, 0.0, 0.0
+        name, total_mb, used_mb = out[0].split(",")
+        total_gb = float(total_mb) / 1024.0
+        used_gb = float(used_mb) / 1024.0
+        return name.strip(), total_gb, max(total_gb - used_gb, 0.0)
+    except Exception:
+        return None, 0.0, 0.0

eigencore/kernels/__init__.py

@@ -0,0 +1,28 @@
+"""Phase 6: own low-level kernels (reference implementations + backend boundary)."""
+
+from eigencore.kernels.q4k import Q4_K_BLOCK_BYTES, QK_K, dequantize_q4_k, quantized_dot_q4_k
+from eigencore.kernels.reference import (
+    Q4_0_BLOCK_SIZE,
+    Q8_0_BLOCK_SIZE,
+    BackendProtocol,
+    ScalarBackend,
+    dequantize_q4_0,
+    dequantize_q8_0,
+    quantized_dot_q8_0,
+    rms_norm,
+)
+
+__all__ = [
+    "Q4_K_BLOCK_BYTES",
+    "QK_K",
+    "Q4_0_BLOCK_SIZE",
+    "Q8_0_BLOCK_SIZE",
+    "BackendProtocol",
+    "ScalarBackend",
+    "dequantize_q4_k",
+    "dequantize_q4_0",
+    "dequantize_q8_0",
+    "quantized_dot_q4_k",
+    "quantized_dot_q8_0",
+    "rms_norm",
+]

eigencore/kernels/q4k.py

@@ -0,0 +1,76 @@
+"""
+Q4_K reference kernel — Stage E slice 1.
+
+GGUF Q4_K super-block layout (256 values = 8 sub-blocks of 32):
+  bytes [0:2)   fp16  d      (super-block scale)
+  bytes [2:4)   fp16  dmin   (super-block min)
+  bytes [4:16)  12 bytes of 8x (6-bit sc + 6-bit min), packed per ggml
+  bytes [16:144) 128 bytes of 4-bit quants, low nibble = even index
+
+Dequant: y[j] = d*sc[b]*q[j] - dmin*m[b]   (ggml uses d*sc*q - dm, note the MINUS)
+
+This is the scalar reference: bit-exact-tested against gguf-py. A future
+SIMD/C-intrinsics kernel must match it within documented tolerance.
+NO performance is claimed here.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+QK_K = 256  # values per Q4_K super-block
+Q4_K_BLOCK_BYTES = 2 + 2 + 12 + QK_K // 2  # 144
+Q4_K_SCALE_SIZE = 12
+
+
+def _get_scale_min(scales: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
+    """Unpack 12 scale bytes into 8 (sc, min) 6-bit pairs (ggml layout)."""
+    scales = np.asarray(scales, dtype=np.uint8).reshape(-1, 3, 4)
+    d, m, m_d = np.split(scales, 3, axis=-2)
+    sc = np.concatenate([d & 0x3F, (m_d & 0x0F) | ((d >> 2) & 0x30)], axis=-1)
+    mn = np.concatenate([m & 0x3F, (m_d >> 4) | ((m >> 2) & 0x30)], axis=-1)
+    return sc.reshape(-1, 8).astype(np.float32), mn.reshape(-1, 8).astype(np.float32)
+
+
+def dequantize_q4_k(blocks: np.ndarray | bytes) -> np.ndarray:
+    """Dequantize Q4_K super-blocks to float32 (n_blocks * 256,).
+
+    Accepts a raw bytes buffer of n*144 bytes, or a uint8 array (n, 144).
+    """
+    if isinstance(blocks, (bytes, bytearray)):
+        raw = np.frombuffer(bytes(blocks), dtype=np.uint8)
+        if raw.size % Q4_K_BLOCK_BYTES != 0:
+            raise ValueError(f"raw buffer not a multiple of {Q4_K_BLOCK_BYTES} bytes")
+        blocks = raw.reshape(-1, Q4_K_BLOCK_BYTES)
+    blocks = np.asarray(blocks, dtype=np.uint8)
+    if blocks.ndim != 2 or blocks.shape[1] != Q4_K_BLOCK_BYTES:
+        raise ValueError(f"expected (n, {Q4_K_BLOCK_BYTES}) blocks, got {blocks.shape}")
+    n_blocks = blocks.shape[0]
+
+    d = blocks[:, 0:2].copy().view(np.float16).astype(np.float32).reshape(n_blocks)
+    dmin = blocks[:, 2:4].copy().view(np.float16).astype(np.float32).reshape(n_blocks)
+    sc, m = _get_scale_min(blocks[:, 4 : 4 + Q4_K_SCALE_SIZE])
+    qs = blocks[:, 4 + Q4_K_SCALE_SIZE :]
+
+    # 4-bit quants: byte j//2 within each 32-value sub-block, low nibble even
+    qs = qs.reshape(n_blocks, -1, 1, 32) >> np.array([0, 4], dtype=np.uint8).reshape(1, 1, 2, 1)
+    qs = (qs & np.uint8(0x0F)).reshape(n_blocks, -1, 32).astype(np.float32)
+
+    d_sc = (d[:, None] * sc).reshape(n_blocks, -1, 1)
+    dm = (dmin[:, None] * m).reshape(n_blocks, -1, 1)
+    return (d_sc * qs - dm).reshape(n_blocks, QK_K).reshape(-1)
+
+
+def quantized_dot_q4_k(packed: np.ndarray | bytes, vec: np.ndarray) -> float:
+    """Dot product of a Q4_K-quantized weight row with a float vector.
+
+    Dequantizes super-block by super-block and accumulates in float32.
+    """
+    w = dequantize_q4_k(packed)
+    v = np.asarray(vec, dtype=np.float32)
+    if w.shape[0] != v.shape[0]:
+        raise ValueError(f"shape mismatch: weights {w.shape} vs vec {v.shape}")
+    acc = 0.0
+    for i in range(0, w.shape[0], QK_K):
+        acc += float(np.dot(w[i : i + QK_K], v[i : i + QK_K]))
+    return acc

eigencore/kernels/reference.py

@@ -0,0 +1,168 @@
+"""
+Scalar reference kernels — Phase 6 slice 1.
+
+These are deliberately simple, correct-by-inspection implementations of the
+core math a custom inference engine needs. They serve two purposes:
+
+1. A trusted reference for differential-testing any future optimized
+   (SIMD/assembly) kernel — an optimized kernel must match these within a
+   documented tolerance.
+2. A backend boundary (`BackendProtocol`) so a future native engine can be
+   swapped in behind the same interface without touching callers.
+
+NO performance is claimed for these. They exist to make correctness
+measurable before optimization.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Protocol
+
+import numpy as np
+
+# GGUF Q8_0 block: 32 values per block, one fp16 scale.
+Q8_0_BLOCK_SIZE = 32
+# GGUF Q4_0 block: 32 values per block (4-bit packed), one fp16 scale.
+Q4_0_BLOCK_SIZE = 32
+# Raw on-disk block sizes: 2-byte fp16 scale + payload.
+Q8_0_BLOCK_BYTES = 2 + Q8_0_BLOCK_SIZE  # 34
+Q4_0_BLOCK_BYTES = 2 + Q4_0_BLOCK_SIZE // 2  # 18
+
+
+class BackendProtocol(Protocol):
+    """Interface a custom/native inference backend must satisfy.
+
+    Implementations (e.g. a future compiled sidecar) plug in here; the
+    llama.cpp path remains the default until a kernel proves itself.
+    """
+
+    def rms_norm(self, x: np.ndarray, weight: np.ndarray, eps: float = 1e-5) -> np.ndarray: ...
+
+    def dequantize_q8_0(self, blocks: np.ndarray) -> np.ndarray: ...
+
+    def dequantize_q4_0(
+        self, packed: np.ndarray, scales: np.ndarray | None = None
+    ) -> np.ndarray: ...
+
+    def dequantize_q4_k(self, blocks: np.ndarray | bytes) -> np.ndarray: ...
+
+    def quantized_dot_q4_k(self, packed: np.ndarray | bytes, vec: np.ndarray) -> float: ...
+
+    def quantized_dot_q8_0(
+        self, packed: np.ndarray, vec: np.ndarray, group_size: int = Q8_0_BLOCK_SIZE
+    ) -> float: ...
+
+
+def rms_norm(x: np.ndarray, weight: np.ndarray, eps: float = 1e-5) -> np.ndarray:
+    """Root-mean-square layer norm: x / rms(x) * weight."""
+    x = np.asarray(x, dtype=np.float32)
+    weight = np.asarray(weight, dtype=np.float32)
+    ms = np.mean(x * x)
+    return x * (1.0 / math.sqrt(float(ms) + eps)) * weight
+
+
+def dequantize_q8_0(blocks: np.ndarray) -> np.ndarray:
+    """Dequantize GGUF Q8_0 blocks.
+
+    `blocks` has shape (n_blocks, 1 + Q8_0_BLOCK_SIZE): column 0 is the fp16
+    scale, the rest are int8 quantized values. Returns float32 vector of
+    length n_blocks * Q8_0_BLOCK_SIZE.
+    """
+    blocks = np.asarray(blocks)
+    if blocks.ndim != 2 or blocks.shape[1] != 1 + Q8_0_BLOCK_SIZE:
+        raise ValueError(f"expected (n, {1 + Q8_0_BLOCK_SIZE}) blocks, got {blocks.shape}")
+    scales = blocks[:, 0].astype(np.float32)
+    quants = blocks[:, 1:].astype(np.float32)
+    return (scales[:, None] * quants).reshape(-1)
+
+
+def dequantize_q4_0(packed: np.ndarray | bytes, scales: np.ndarray | None = None) -> np.ndarray:
+    """Dequantize GGUF Q4_0 blocks (ggml layout).
+
+    ggml packs 32 values into 16 bytes per block: byte j holds element j in
+    its LOW nibble and element j+16 in its HIGH nibble (strided, not
+    interleaved), each nibble biased by -8 and scaled by the block's fp16
+    scale. Accepts either (a) a raw bytes buffer of n_blocks × 18-byte
+    blocks, or (b) `packed` uint8 (n, 16) plus `scales` fp16 (n,).
+    Returns float32 of length n_blocks * Q4_0_BLOCK_SIZE.
+    """
+    if isinstance(packed, (bytes, bytearray)):
+        raw = np.frombuffer(bytes(packed), dtype=np.uint8)
+        if raw.size % Q4_0_BLOCK_BYTES != 0:
+            raise ValueError(f"raw buffer not a multiple of {Q4_0_BLOCK_BYTES} bytes")
+        blocks = raw.reshape(-1, Q4_0_BLOCK_BYTES)
+        scales = blocks[:, :2].copy().view(np.float16).astype(np.float32).reshape(-1)
+        packed = blocks[:, 2:]
+    else:
+        packed = np.asarray(packed)
+        if scales is None:
+            raise ValueError("scales required when packed is an array")
+        scales = np.asarray(scales, dtype=np.float32)
+        if packed.ndim != 2 or packed.shape[1] != Q4_0_BLOCK_SIZE // 2:
+            raise ValueError(f"expected (n, {Q4_0_BLOCK_SIZE // 2}) packed, got {packed.shape}")
+        if scales.shape[0] != packed.shape[0]:
+            raise ValueError("scales/packed block count mismatch")
+    low = (packed & 0x0F).astype(np.float32) - 8.0
+    high = (packed >> 4).astype(np.float32) - 8.0
+    # ggml strided order: low nibbles fill elements 0..15, high nibbles 16..31
+    out = np.empty((packed.shape[0], Q4_0_BLOCK_SIZE), dtype=np.float32)
+    out[:, : Q4_0_BLOCK_SIZE // 2] = low
+    out[:, Q4_0_BLOCK_SIZE // 2 :] = high
+    return (scales[:, None] * out).reshape(-1)
+
+
+def quantized_dot_q8_0(
+    packed: np.ndarray, vec: np.ndarray, group_size: int = Q8_0_BLOCK_SIZE
+) -> float:
+    """Dot product of a Q8_0-quantized weight with a float vector.
+
+    Dequantizes block-by-block and accumulates in float32. This is the
+    hot inner loop of CPU LLM decode, so it's the first kernel a native
+    implementation would replace.
+    """
+    w = dequantize_q8_0(packed)
+    v = np.asarray(vec, dtype=np.float32)
+    if w.shape[0] != v.shape[0]:
+        raise ValueError(f"shape mismatch: weights {w.shape} vs vec {v.shape}")
+    n_groups = w.shape[0] // group_size
+    acc = 0.0
+    for g in range(n_groups):
+        acc += float(
+            np.dot(
+                w[g * group_size : (g + 1) * group_size], v[g * group_size : (g + 1) * group_size]
+            )
+        )
+    return acc
+
+
+class ScalarBackend:
+    """Reference implementation of BackendProtocol (NumPy, scalar loops)."""
+
+    name = "scalar-numpy"
+
+    def rms_norm(self, x: np.ndarray, weight: np.ndarray, eps: float = 1e-5) -> np.ndarray:
+        return rms_norm(x, weight, eps)
+
+    def dequantize_q8_0(self, blocks: np.ndarray) -> np.ndarray:
+        return dequantize_q8_0(blocks)
+
+    def dequantize_q4_0(
+        self, packed: np.ndarray | bytes, scales: np.ndarray | None = None
+    ) -> np.ndarray:
+        return dequantize_q4_0(packed, scales)
+
+    def quantized_dot_q8_0(
+        self, packed: np.ndarray, vec: np.ndarray, group_size: int = Q8_0_BLOCK_SIZE
+    ) -> float:
+        return quantized_dot_q8_0(packed, vec, group_size)
+
+    def dequantize_q4_k(self, blocks: np.ndarray | bytes) -> np.ndarray:
+        from eigencore.kernels.q4k import dequantize_q4_k
+
+        return dequantize_q4_k(blocks)
+
+    def quantized_dot_q4_k(self, packed: np.ndarray | bytes, vec: np.ndarray) -> float:
+        from eigencore.kernels.q4k import quantized_dot_q4_k
+
+        return quantized_dot_q4_k(packed, vec)

eigencore/models/__init__.py

@@ -0,0 +1,3 @@
+from eigencore.models.registry import ModelRegistry, ModelSpec
+
+__all__ = ["ModelRegistry", "ModelSpec"]