engram: batch-cosine Adapter/Strategy/Factory over ggml, supersedes hand-rolled PR #114

Stop hand-rolling GPU kernels for batch cosine similarity — use ggml (the MIT-licensed compute library underneath llama.cpp, installed standalone via Homebrew) as the preferred backend, without ripping out PR #114's carefully-verified hand-rolled Metal shader. Structure: one stable public adapter (eg_cosine_batch.h, zero #ifdef at call sites) backed by three selectable concrete Strategies behind an internal vtable (eg_cosine_batch_strategy.h) chosen by a Factory (eg_cosine_batch.c): - eg_cosine_batch_strategy_ggml.c — NEW. ggml + dynamically-loaded Metal backend plugin (ggml_backend_load_all_from_path + ggml_mul_mat for the batched dot product), gather/scatter around the -2.0 sentinel contract. - eg_cosine_batch_strategy_metal_hand.m — PR #114's original hand-rolled Metal shader bridge, preserved almost verbatim, now one strategy among several rather than the only option. eg_cosine_batch.metal kept byte-identical to the original. - eg_cosine_batch_strategy_cpu.c — universal always-false fallback (direct descendant of PR #114's eg_metal_cosine_stub.c). Selection: EL_COSINE_BATCH_STRATEGY=ggml|metal|cpu|auto (default: ggml first, then hand-rolled Metal, then CPU — first available wins), plus back-compat EL_METAL_COSINE=0 to disable every GPU-backed strategy. build_vindex_bench.sh compiles all three strategies on Darwin, CPU-fallback-only elsewhere. vindex_bench.c now reports BRUTE-GGML and BRUTE-METAL side by side against the same CPU oracle, on the same dataset, in one run (real numbers vs. real store snapshot in the PR body).
2026-08-15 17:16:41 -05:00
parent 2555e363a6
commit b3f410fc91
9 changed files with 1372 additions and 5 deletions
@@ -0,0 +1,51 @@
+#!/bin/bash
+# build_vindex_bench.sh — build the vindex_bench oracle/proof harness, with
+# the real ggml + hand-rolled-Metal batch-cosine strategies on Darwin and a
+# zero-dependency CPU-only stub everywhere else. Mirrors the two-step recipe
+# documented in vindex_bench.c's own header comment; this script exists so
+# that recipe is one command, not a copy-pasted paragraph.
+#
+# Darwin build links FOUR strategy translation units:
+#   eg_cosine_batch.c                    — the Factory (always)
+#   eg_cosine_batch_strategy_cpu.c       — universal fallback (always)
+#   eg_cosine_batch_strategy_ggml.c      — ggml + dynamic Metal backend plugin
+#   eg_cosine_batch_strategy_metal_hand.m — PR #114's original hand-rolled
+#                                            Metal shader, preserved as one
+#                                            selectable strategy
+# plus -DEG_HAVE_STRATEGY_GGML -DEG_HAVE_STRATEGY_METAL_HAND so the Factory
+# (and vindex_bench.c's own direct strategy comparison) knows both exist.
+#
+# ggml is resolved via `brew --prefix ggml` when available (portable across
+# Intel /usr/local and Apple Silicon /opt/homebrew installs), falling back to
+# /opt/homebrew if brew isn't on PATH. Override with GGML_PREFIX=... env var.
+#
+# Usage: ./build_vindex_bench.sh [output_path]
+set -euo pipefail
+cd "$(dirname "$0")"
+OUT="${1:-./vindex_bench}"
+CC="${CC:-cc}"
+
+if [ "$(uname -s)" = "Darwin" ]; then
+  GGML_PREFIX="${GGML_PREFIX:-$(brew --prefix ggml 2>/dev/null || echo /opt/homebrew)}"
+  echo "== Darwin: building with the ggml + hand-rolled-Metal strategies (ggml prefix: $GGML_PREFIX) =="
+
+  "$CC" -O2 -std=c11 -x objective-c \
+    -c eg_cosine_batch_strategy_metal_hand.m -o /tmp/eg_cosine_batch_strategy_metal_hand.o \
+    -framework Metal -framework Foundation
+
+  "$CC" -O2 -std=c11 -DEG_HAVE_STRATEGY_GGML -DEG_HAVE_STRATEGY_METAL_HAND -w \
+    -I"$GGML_PREFIX/include" \
+    vindex_bench.c engram_vindex.c \
+    eg_cosine_batch.c eg_cosine_batch_strategy_cpu.c eg_cosine_batch_strategy_ggml.c \
+    /tmp/eg_cosine_batch_strategy_metal_hand.o \
+    -L"$GGML_PREFIX/lib" -lggml -lggml-base \
+    -Wl,-rpath,"$GGML_PREFIX/lib" \
+    -lm -framework Metal -framework Foundation -o "$OUT"
+else
+  echo "== non-Darwin: building with the CPU-only fallback strategy (no ggml, no Metal) =="
+  "$CC" -O2 -std=c11 -w vindex_bench.c engram_vindex.c \
+    eg_cosine_batch.c eg_cosine_batch_strategy_cpu.c \
+    -lm -o "$OUT"
+fi
+
+echo "built: $OUT"