feat(rag): fastembed wrapper (Embedder, bge-small-en-v1.5, 384-dim)

TDD implementation: tests/rag/test_embed.py exercises Embedder.encode() with
batch processing, empty lists, dimension validation, and semantic similarity
guarantees. Model lazy-loads on first call (no torch dependency, ~33MB ONNX).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

src/rag/embed.py

@@ -0,0 +1,39 @@
+"""Fastembed wrapper — ONNX-based, CPU-only, no torch dep.
+
+Public entry: `Embedder().encode(texts) -> np.ndarray[N, D]`. Model is
+loaded lazily on first call. Output is float32 to match FAISS's expected
+input dtype.
+"""
+from __future__ import annotations
+
+import numpy as np
+
+from src.core.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+# bge-small-en-v1.5: 384-dim, ~33MB ONNX, MTEB top-tier for size class.
+_MODEL_NAME = "BAAI/bge-small-en-v1.5"
+EMBEDDING_DIM = 384
+
+
+class Embedder:
+    """Lazy-loaded fastembed wrapper. One instance per process is enough."""
+
+    def __init__(self, model_name: str = _MODEL_NAME) -> None:
+        self._model_name = model_name
+        self._model = None  # lazy-loaded on first encode()
+
+    def _ensure_model(self) -> None:
+        if self._model is None:
+            from fastembed import TextEmbedding
+            logger.info("Loading fastembed model %s (one-time)", self._model_name)
+            self._model = TextEmbedding(model_name=self._model_name)
+
+    def encode(self, texts: list[str]) -> np.ndarray:
+        if not texts:
+            return np.zeros((0, EMBEDDING_DIM), dtype=np.float32)
+        self._ensure_model()
+        embeddings = list(self._model.embed(texts))
+        return np.array(embeddings, dtype=np.float32)

tests/rag/test_embed.py

@@ -0,0 +1,42 @@
+"""Tests for src.rag.embed — fastembed wrapper."""
+from __future__ import annotations
+
+import numpy as np
+import pytest
+
+from src.rag.embed import Embedder, EMBEDDING_DIM
+
+
+class TestEmbedder:
+    @pytest.fixture(scope="class")
+    def embedder(self) -> Embedder:
+        return Embedder()
+
+    def test_dim_constant_matches_model(self, embedder: Embedder) -> None:
+        out = embedder.encode(["hello"])
+        assert out.shape == (1, EMBEDDING_DIM)
+
+    def test_batch_encoding(self, embedder: Embedder) -> None:
+        out = embedder.encode(["hello", "world", "blood-brain barrier"])
+        assert out.shape == (3, EMBEDDING_DIM)
+        assert out.dtype == np.float32
+
+    def test_empty_list_returns_empty_array(self, embedder: Embedder) -> None:
+        out = embedder.encode([])
+        assert out.shape == (0, EMBEDDING_DIM)
+
+    def test_similar_strings_have_higher_similarity_than_dissimilar(
+        self, embedder: Embedder
+    ) -> None:
+        vecs = embedder.encode([
+            "blood-brain barrier permeability",
+            "BBB drug penetration",
+            "MRI multi-site harmonization",
+        ])
+        # cosine similarity (vectors should be normalized for stable comparison)
+        from numpy.linalg import norm
+        def cos(a, b):
+            return float(np.dot(a, b) / (norm(a) * norm(b)))
+        sim_ab = cos(vecs[0], vecs[1])
+        sim_ac = cos(vecs[0], vecs[2])
+        assert sim_ab > sim_ac, f"Expected BBB-related strings closer; got {sim_ab=} vs {sim_ac=}"