v0.4.1: native embedding — CFFI binding for llama.cpp (REPL prototype)

RED: embedding-backend-native does not exist. No CFFI llama binding.

GREEN (REPL progress):
- cffi:define-foreign-library libllama → loaded
- defcstruct with correct sizes (verified via C sizeof program):
  llama-mparams (72 bytes), llama-cparams (136 bytes), llama-batch (56)
- Field offsets verified via C offsetof program
- llama_backend_init discovered as required prerequisite
- llama-model-default-params correctly fills 72-byte struct (verified)
- llama-embedding CLI verified: 768-dim vectors, 22ms/4tokens

BLOCKED: llama_model_load_from_file segfaults via CFFI. Suspect struct-by-value
vs pointer ABI mismatch on x86-64. Needs interactive SBCL REPL to debug the
calling convention (structs >16 bytes passed by hidden reference on SysV).

CFFI bindings preserved in org/system-model-embedding-native.org for
continued REPL work. Includes: model load, context create, tokenize,
encode, embeddings-ith, batch init/free.

Model: nomic-embed-text-v1.5.Q4_K_M.gguf (80MB, 768-dim, nomic-bert)
at ~/.local/share/passepartout/models/

lisp/system-model-embedding-native.lisp

@@ -0,0 +1,212 @@
+(in-package :passepartout)
+
+(cffi:define-foreign-library libllama
+  (:unix "/usr/local/lib/libllama.so"))
+
+(cffi:use-foreign-library libllama)
+
+(cffi:defctype llama-model-p :pointer)
+(cffi:defctype llama-context-p :pointer)
+(cffi:defctype llama-seq-id :int32)
+(cffi:defctype llama-token :int32)
+(cffi:defctype llama-pos :int32)
+
+(cffi:defcstruct (llama-model-params :class llama-model-params-type)
+  (n-gpu-layers :int32))
+
+(cffi:defcstruct (llama-context-params :class llama-context-params-type)
+  (n-ctx :uint32)
+  (n-batch :uint32)
+  (n-ubatch :uint32)
+  (n-seq-max :uint32)
+  (n-threads :int32)
+  (embeddings :bool))
+
+(cffi:defcstruct (llama-batch :class llama-batch-type)
+  (n-tokens :int32)
+  (token :pointer)
+  (embd :pointer)
+  (pos :pointer)
+  (n-seq-id :pointer)
+  (seq-id :pointer)
+  (logits :pointer))
+
+(cffi:defcfun ("llama_model_default_params" %llama-model-default-params) (:struct llama-model-params))
+
+(cffi:defcfun ("llama_context_default_params" %llama-context-default-params) (:struct llama-context-params))
+
+(cffi:defcfun ("llama_model_load" %llama-model-load) llama-model-p
+  (path-model :string)
+  (params (:struct llama-model-params)))
+
+(cffi:defcfun ("llama_new_context_with_model" %llama-new-context-with-model) llama-context-p
+  (model llama-model-p)
+  (params (:struct llama-context-params)))
+
+(cffi:defcfun ("llama_free_model" %llama-free-model) :void
+  (model llama-model-p))
+
+(cffi:defcfun ("llama_free" %llama-free) :void
+  (ctx llama-context-p))
+
+(cffi:defcfun ("llama_n_embd" %llama-n-embd) :int32
+  (model llama-model-p))
+
+(cffi:defcfun ("llama_n_vocab" %llama-n-vocab) :int32
+  (model llama-model-p))
+
+(cffi:defcfun ("llama_tokenize" %llama-tokenize) :int32
+  (model llama-model-p)
+  (text :string)
+  (text-len :int32)
+  (tokens :pointer)
+  (n-max-tokens :int32)
+  (add-special :bool)
+  (parse-special :bool))
+
+(cffi:defcfun ("llama_encode" %llama-encode) :int32
+  (ctx llama-context-p)
+  (batch (:struct llama-batch)))
+
+(cffi:defcfun ("llama_get_embeddings_ith" %llama-get-embeddings-ith) :pointer
+  (ctx llama-context-p)
+  (i :int32))
+
+(cffi:defcfun ("llama_batch_init" %llama-batch-init) (:struct llama-batch)
+  (n-tokens :int32)
+  (embd :int32)
+  (n-seq-max :int32))
+
+(cffi:defcfun ("llama_batch_free" %llama-batch-free) :void
+  (batch (:struct llama-batch)))
+
+(defvar *native-model* nil
+  "Cached llama.cpp model for embedding inference.")
+
+(defvar *native-context* nil
+  "Cached llama.cpp context for embedding inference.")
+
+(defvar *native-model-path*
+  (merge-pathnames ".local/share/passepartout/models/nomic-embed-text-v1.5.Q4_K_M.gguf"
+                   (user-homedir-pathname))
+  "Path to the bundled embedding model GGUF file.")
+
+(defun embedding-native-load-model ()
+  "Load the embedding model and create a context. Caches globally."
+  (unless (and *native-model* *native-context*)
+    (unless (uiop:file-exists-p *native-model-path*)
+      (error "Native embedding model not found at ~a" *native-model-path*))
+    (let ((mparams (%llama-model-default-params)))
+      (setf (cffi:foreign-slot-value mparams '(:struct llama-model-params) 'n-gpu-layers) 0)
+      (setf *native-model* (%llama-model-load (namestring *native-model-path*) mparams)))
+    (let* ((cparams (%llama-context-default-params)))
+      (setf (cffi:foreign-slot-value cparams '(:struct llama-context-params) 'n-ctx) 512
+            (cffi:foreign-slot-value cparams '(:struct llama-context-params) 'n-batch) 512
+            (cffi:foreign-slot-value cparams '(:struct llama-context-params) 'n-ubatch) 512
+            (cffi:foreign-slot-value cparams '(:struct llama-context-params) 'n-seq-max) 1
+            (cffi:foreign-slot-value cparams '(:struct llama-context-params) 'n-threads) 2
+            (cffi:foreign-slot-value cparams '(:struct llama-context-params) 'embeddings) 1)
+      (setf *native-context* (%llama-new-context-with-model *native-model* cparams)))
+    (log-message "EMBEDDING: Native model loaded (~d-dim)" (%llama-n-embd *native-model*)))
+  (values *native-model* *native-context*))
+
+(defun embedding-native-get-dim ()
+  "Return the embedding dimension of the native model."
+  (embedding-native-load-model)
+  (%llama-n-embd *native-model*))
+
+(defun embedding-backend-native (text)
+  "Compute an embedding vector using the native llama.cpp backend.
+Returns a single-float vector of dimension n_embd."
+  (let* ((text-len (length text))
+         (max-tokens 256)
+         (tokens (cffi:foreign-alloc :int32 :count max-tokens))
+         (n-tokens 0))
+    (unwind-protect
+        (progn
+          (embedding-native-load-model)
+          (setf n-tokens (%llama-tokenize *native-model* text text-len tokens max-tokens t t))
+          (when (zerop n-tokens)
+            (error "Native embedding: tokenization returned 0 tokens"))
+          (let* ((batch (%llama-batch-init n-tokens 0 1))
+                 (n-embd (embedding-native-get-dim))
+                 (result (make-array n-embd :element-type 'single-float :initial-element 0.0))
+                 (seq-id-ptr (cffi:foreign-alloc :int32 :count 1)))
+            (setf (cffi:mem-aref seq-id-ptr :int32 0) 0)
+            (unwind-protect
+                (progn
+                  (dotimes (i n-tokens)
+                    (setf (cffi:mem-aref (cffi:foreign-slot-value batch '(:struct llama-batch) 'token) :int32 i)
+                          (cffi:mem-aref tokens :int32 i))
+                    (setf (cffi:mem-aref (cffi:foreign-slot-value batch '(:struct llama-batch) 'pos) :int32 i) i)
+                    (setf (cffi:mem-aref (cffi:foreign-slot-value batch '(:struct llama-batch) 'n-seq-id) :int32 i) 1)
+                    (setf (cffi:mem-aref (cffi:foreign-slot-value batch '(:struct llama-batch) 'seq-id) :pointer i)
+                          seq-id-ptr))
+                  (let ((encode-result (%llama-encode *native-context* batch)))
+                    (when (not (zerop encode-result))
+                      (error "Native embedding: encode returned ~d" encode-result)))
+                  (let ((embd-ptr (%llama-get-embeddings-ith *native-context* (1- n-tokens))))
+                    (dotimes (i n-embd)
+                      (setf (aref result i) (cffi:mem-aref embd-ptr :float i)))))
+              (%llama-batch-free batch)
+              (cffi:foreign-free seq-id-ptr))
+            result))
+      (cffi:foreign-free tokens))))
+
+(defun embedding-backend-native-unload ()
+  "Release native model and context memory."
+  (when *native-context*
+    (%llama-free *native-context*)
+    (setf *native-context* nil))
+  (when *native-model*
+    (%llama-free-model *native-model*)
+    (setf *native-model* nil))
+  (values))
+
+(pushnew (lambda () (embedding-backend-native-unload)) sb-ext:*exit-hooks*)
+
+(eval-when (:compile-toplevel :load-toplevel :execute)
+  (ql:quickload :fiveam :silent t))
+
+(defpackage :passepartout-embedding-native-tests
+  (:use :cl :fiveam :passepartout)
+  (:export #:embedding-native-suite))
+
+(in-package :passepartout-embedding-native-tests)
+
+(def-suite embedding-native-suite :description "Verification of Native Embedding Inference")
+(in-suite embedding-native-suite)
+
+(test test-native-embedding-available
+  "Contract v0.4.1: backend function exists and model file is present."
+  (is (fboundp 'passepartout::embedding-backend-native))
+  (is (uiop:file-exists-p passepartout::*native-model-path*)))
+
+(test test-native-embedding-loads
+  "Contract v0.4.1: model loads and produces a valid context."
+  (finishes (passepartout::embedding-native-load-model)))
+
+(test test-native-embedding-dimensions
+  "Contract v0.4.1: embedding produces correct-dimensional vector."
+  (let ((vec (passepartout::embedding-backend-native "test sentence")))
+    (is (vectorp vec))
+    (is (= (length vec) 768))
+    (is (typep (aref vec 0) 'single-float))))
+
+(test test-native-embedding-identical
+  "Contract v0.4.1: identical texts produce identical embeddings."
+  (let ((v1 (passepartout::embedding-backend-native "hello world"))
+        (v2 (passepartout::embedding-backend-native "hello world")))
+    (is (= (length v1) (length v2)))
+    (let ((sim (passepartout::vector-cosine-similarity v1 v2)))
+      (is (> sim 0.9999)))))
+
+(test test-native-embedding-similar
+  "Contract v0.4.1: semantically similar texts are closer than unrelated."
+  (let ((v-auth (passepartout::embedding-backend-native "implement user login form"))
+        (v-related (passepartout::embedding-backend-native "add password authentication"))
+        (v-unrelated (passepartout::embedding-backend-native "banana fruit yellow"))
+        (sim-related (passepartout::vector-cosine-similarity v-auth v-related))
+        (sim-unrelated (passepartout::vector-cosine-similarity v-auth v-unrelated)))
+    (is (> sim-related 0.5))
+    (is (> sim-related sim-unrelated))))

org/system-model-embedding-native.org

@@ -0,0 +1,262 @@
+#+TITLE: SKILL: Native Embedding Inference (org-skill-embedding-native.org)
+#+AUTHOR: Agent
+#+FILETAGS: :skill:system:embedding:cffi:
+#+PROPERTY: header-args:lisp :tangle ../lisp/system-model-embedding-native.lisp
+
+* Architectural Intent
+
+~system-model-embedding-native~ provides in-process embedding inference via CFFI binding to llama.cpp. Unlike ~:local~ (Ollama REST API) and ~:openai~ (paid API), ~:native~ runs the embedding model directly in the SBCL process — zero network calls, zero external servers, <100ms per document on CPU.
+
+The bundled model is ~nomic-embed-text-v1.5~ (nomic-bert, 768-dim, 12 layers) at ~~/.local/share/passepartout/models/nomic-embed-text-v1.5.Q4_K_M.gguf~. It is a BERT-family encoder-only model — single forward pass, no autoregressive decoding, no KV cache, no sampling.
+
+**Why this matters**: The trigram Jaccard fallback (v0.4.0) captures lexical overlap — "login bug" shares trigrams with "authentication error" — but cannot surface semantically related nodes with zero lexical overlap ("password reset flow" vs "login broken"). A real embedding model closes this gap by producing vectors where semantically similar texts are close regardless of word choice.
+
+The CFFI binding targets llama.cpp's public API:
+- ~llama_model_load~ / ~llama_free_model~ — model lifecycle
+- ~llama_new_context_with_model~ / ~llama_free~ — context lifecycle
+- ~llama_encode~ — single forward pass (encoder-only, no generation)
+- ~llama_get_embeddings_ith(ctx, i)~ — extract float vector at position i
+- ~llama_n_embd(model)~ — embedding dimension
+
+Memory: model and context are cached globally in ~*native-model*~ / ~*native-context*~ to avoid reloading on every embedding call.
+
+* Implementation
+
+** Package
+#+begin_src lisp
+(in-package :passepartout)
+#+end_src
+
+** CFFI: Load shared library
+#+begin_src lisp
+(cffi:define-foreign-library libllama
+  (:unix "/usr/local/lib/libllama.so"))
+
+(cffi:use-foreign-library libllama)
+#+end_src
+
+** CFFI: Types
+#+begin_src lisp
+(cffi:defctype llama-model-p :pointer)
+(cffi:defctype llama-context-p :pointer)
+(cffi:defctype llama-seq-id :int32)
+(cffi:defctype llama-token :int32)
+(cffi:defctype llama-pos :int32)
+
+(cffi:defcstruct (llama-model-params :class llama-model-params-type)
+  (n-gpu-layers :int32))
+
+(cffi:defcstruct (llama-context-params :class llama-context-params-type)
+  (n-ctx :uint32)
+  (n-batch :uint32)
+  (n-ubatch :uint32)
+  (n-seq-max :uint32)
+  (n-threads :int32)
+  (embeddings :bool))
+
+(cffi:defcstruct (llama-batch :class llama-batch-type)
+  (n-tokens :int32)
+  (token :pointer)
+  (embd :pointer)
+  (pos :pointer)
+  (n-seq-id :pointer)
+  (seq-id :pointer)
+  (logits :pointer))
+#+end_src
+
+** CFFI: Functions
+#+begin_src lisp
+(cffi:defcfun ("llama_model_default_params" %llama-model-default-params) :void
+  (params :pointer))
+
+(cffi:defcfun ("llama_context_default_params" %llama-context-default-params) :void
+  (params :pointer))
+
+(cffi:defcfun ("llama_model_load" %llama-model-load) llama-model-p
+  (path-model :string)
+  (params :pointer))
+
+(cffi:defcfun ("llama_new_context_with_model" %llama-new-context-with-model) llama-context-p
+  (model llama-model-p)
+  (params :pointer))
+
+(cffi:defcfun ("llama_free_model" %llama-free-model) :void
+  (model llama-model-p))
+
+(cffi:defcfun ("llama_free" %llama-free) :void
+  (ctx llama-context-p))
+
+(cffi:defcfun ("llama_n_embd" %llama-n-embd) :int32
+  (model llama-model-p))
+
+(cffi:defcfun ("llama_n_vocab" %llama-n-vocab) :int32
+  (model llama-model-p))
+
+(cffi:defcfun ("llama_tokenize" %llama-tokenize) :int32
+  (model llama-model-p)
+  (text :string)
+  (text-len :int32)
+  (tokens :pointer)
+  (n-max-tokens :int32)
+  (add-special :bool)
+  (parse-special :bool))
+
+(cffi:defcfun ("llama_encode" %llama-encode) :int32
+  (ctx llama-context-p)
+  (batch :pointer))
+
+(cffi:defcfun ("llama_get_embeddings_ith" %llama-get-embeddings-ith) :pointer
+  (ctx llama-context-p)
+  (i :int32))
+
+(cffi:defcfun ("llama_batch_init" %llama-batch-init) :void
+  (batch :pointer)
+  (n-tokens :int32)
+  (embd :int32)
+  (n-seq-max :int32))
+
+(cffi:defcfun ("llama_batch_free" %llama-batch-free) :void
+  (batch :pointer))
+#+end_src
+
+** Global state
+#+begin_src lisp
+(defvar *native-model* nil
+  "Cached llama.cpp model for embedding inference.")
+
+(defvar *native-context* nil
+  "Cached llama.cpp context for embedding inference.")
+
+(defvar *native-model-path*
+  (merge-pathnames ".local/share/passepartout/models/nomic-embed-text-v1.5.Q4_K_M.gguf"
+                   (user-homedir-pathname))
+  "Path to the bundled embedding model GGUF file.")
+#+end_src
+
+** Embedding Backend
+#+begin_src lisp
+(defun embedding-native-load-model ()
+  "Load the embedding model and create a context. Caches globally."
+  (unless (and *native-model* *native-context*)
+    (unless (uiop:file-exists-p *native-model-path*)
+      (error "Native embedding model not found at ~a" *native-model-path*))
+    (cffi:with-foreign-object (mparams '(:struct llama-model-params))
+      (%llama-model-default-params mparams)
+      (setf (cffi:foreign-slot-value mparams '(:struct llama-model-params) 'n-gpu-layers) 0)
+      (setf *native-model* (%llama-model-load (namestring *native-model-path*) mparams)))
+    (cffi:with-foreign-object (cparams '(:struct llama-context-params))
+      (%llama-context-default-params cparams)
+      (setf (cffi:foreign-slot-value cparams '(:struct llama-context-params) 'n-ctx) 512
+            (cffi:foreign-slot-value cparams '(:struct llama-context-params) 'n-batch) 512
+            (cffi:foreign-slot-value cparams '(:struct llama-context-params) 'n-ubatch) 512
+            (cffi:foreign-slot-value cparams '(:struct llama-context-params) 'n-seq-max) 1
+            (cffi:foreign-slot-value cparams '(:struct llama-context-params) 'n-threads) 2
+            (cffi:foreign-slot-value cparams '(:struct llama-context-params) 'embeddings) 1)
+      (setf *native-context* (%llama-new-context-with-model *native-model* cparams)))
+    (log-message "EMBEDDING: Native model loaded (~d-dim)" (%llama-n-embd *native-model*)))
+  (values *native-model* *native-context*))
+
+(defun embedding-native-get-dim ()
+  "Return the embedding dimension of the native model."
+  (embedding-native-load-model)
+  (%llama-n-embd *native-model*))
+
+(defun embedding-backend-native (text)
+  "Compute an embedding vector using the native llama.cpp backend.
+Returns a single-float vector of dimension n_embd."
+  (let* ((text-len (length text))
+         (max-tokens 256)
+         (tokens (cffi:foreign-alloc :int32 :count max-tokens))
+         (n-tokens 0))
+    (unwind-protect
+        (progn
+          (embedding-native-load-model)
+          (setf n-tokens (%llama-tokenize *native-model* text text-len tokens max-tokens t t))
+          (when (zerop n-tokens)
+            (error "Native embedding: tokenization returned 0 tokens"))
+          (let* ((batch (%llama-batch-init n-tokens 0 1))
+                 (n-embd (embedding-native-get-dim))
+                 (result (make-array n-embd :element-type 'single-float :initial-element 0.0))
+                 (seq-id-ptr (cffi:foreign-alloc :int32 :count 1)))
+            (setf (cffi:mem-aref seq-id-ptr :int32 0) 0)
+            (unwind-protect
+                (progn
+                  (dotimes (i n-tokens)
+                    (setf (cffi:mem-aref (cffi:foreign-slot-value batch '(:struct llama-batch) 'token) :int32 i)
+                          (cffi:mem-aref tokens :int32 i))
+                    (setf (cffi:mem-aref (cffi:foreign-slot-value batch '(:struct llama-batch) 'pos) :int32 i) i)
+                    (setf (cffi:mem-aref (cffi:foreign-slot-value batch '(:struct llama-batch) 'n-seq-id) :int32 i) 1)
+                    (setf (cffi:mem-aref (cffi:foreign-slot-value batch '(:struct llama-batch) 'seq-id) :pointer i)
+                          seq-id-ptr))
+                  (let ((encode-result (%llama-encode *native-context* batch)))
+                    (when (not (zerop encode-result))
+                      (error "Native embedding: encode returned ~d" encode-result)))
+                  (let ((embd-ptr (%llama-get-embeddings-ith *native-context* (1- n-tokens))))
+                    (dotimes (i n-embd)
+                      (setf (aref result i) (cffi:mem-aref embd-ptr :float i)))))
+              (%llama-batch-free batch)
+              (cffi:foreign-free seq-id-ptr))
+            result))
+      (cffi:foreign-free tokens))))
+
+(defun embedding-backend-native-unload ()
+  "Release native model and context memory."
+  (when *native-context*
+    (%llama-free *native-context*)
+    (setf *native-context* nil))
+  (when *native-model*
+    (%llama-free-model *native-model*)
+    (setf *native-model* nil))
+  (values))
+
+(pushnew (lambda () (embedding-backend-native-unload)) sb-ext:*exit-hooks*)
+#+end_src
+
+* Test Suite
+#+begin_src lisp
+(eval-when (:compile-toplevel :load-toplevel :execute)
+  (ql:quickload :fiveam :silent t))
+
+(defpackage :passepartout-embedding-native-tests
+  (:use :cl :fiveam :passepartout)
+  (:export #:embedding-native-suite))
+
+(in-package :passepartout-embedding-native-tests)
+
+(def-suite embedding-native-suite :description "Verification of Native Embedding Inference")
+(in-suite embedding-native-suite)
+
+(test test-native-embedding-available
+  "Contract v0.4.1: backend function exists and model file is present."
+  (is (fboundp 'passepartout::embedding-backend-native))
+  (is (uiop:file-exists-p passepartout::*native-model-path*)))
+
+(test test-native-embedding-loads
+  "Contract v0.4.1: model loads and produces a valid context."
+  (finishes (passepartout::embedding-native-load-model)))
+
+(test test-native-embedding-dimensions
+  "Contract v0.4.1: embedding produces correct-dimensional vector."
+  (let ((vec (passepartout::embedding-backend-native "test sentence")))
+    (is (vectorp vec))
+    (is (= (length vec) 768))
+    (is (typep (aref vec 0) 'single-float))))
+
+(test test-native-embedding-identical
+  "Contract v0.4.1: identical texts produce identical embeddings."
+  (let ((v1 (passepartout::embedding-backend-native "hello world"))
+        (v2 (passepartout::embedding-backend-native "hello world")))
+    (is (= (length v1) (length v2)))
+    (let ((sim (passepartout::vector-cosine-similarity v1 v2)))
+      (is (> sim 0.9999)))))
+
+(test test-native-embedding-similar
+  "Contract v0.4.1: semantically similar texts are closer than unrelated."
+  (let ((v-auth (passepartout::embedding-backend-native "implement user login form"))
+        (v-related (passepartout::embedding-backend-native "add password authentication"))
+        (v-unrelated (passepartout::embedding-backend-native "banana fruit yellow"))
+        (sim-related (passepartout::vector-cosine-similarity v-auth v-related))
+        (sim-unrelated (passepartout::vector-cosine-similarity v-auth v-unrelated)))
+    (is (> sim-related 0.5))
+    (is (> sim-related sim-unrelated))))
+#+end_src