""" Local embedding generation using sentence-transformers. Zero API cost. Model loaded once at startup (singleton via lifespan). Batch processing for efficiency at 100k scale. Model: all-MiniLM-L6-v2 - 384 dimensions - ~80 MB on disk - ~100ms per batch of 64 on CPU - Embeddings are L2-normalized → cosine similarity = dot product """ import logging import threading from typing import Optional import numpy as np logger = logging.getLogger(__name__) _model = None _model_lock = threading.Lock() def load_model(model_name: str = "all-MiniLM-L6-v2") -> None: """Load (or warm up) the embedding model. Call once at startup.""" global _model with _model_lock: if _model is not None: return logger.info(f"Loading embedding model: {model_name}") try: from sentence_transformers import SentenceTransformer _model = SentenceTransformer(model_name) logger.info("Embedding model ready") except Exception as e: logger.error(f"Failed to load embedding model: {e}") raise def _get_model(): global _model if _model is None: load_model() return _model def embed_texts(texts: list[str], batch_size: int = 64) -> np.ndarray: """ Embed a list of texts. Returns ndarray of shape (N, 384), L2-normalized. Cosine similarity between two rows = their dot product. """ model = _get_model() if not texts: return np.empty((0, 384), dtype=np.float32) embeddings = model.encode( texts, normalize_embeddings=True, batch_size=batch_size, show_progress_bar=False, ) return embeddings.astype(np.float32) def embed_single(text: str) -> np.ndarray: """Embed one text. Returns shape (384,).""" return embed_texts([text])[0] def cosine_similarity(a: np.ndarray, b: np.ndarray) -> float: """ Cosine similarity between two L2-normalized vectors. Since both are normalized, dot product == cosine similarity. Returns value in [-1, 1]. """ return float(np.dot(a, b)) def normalize_similarity(sim: float) -> float: """Map [-1, 1] similarity to [0, 1] score.""" return (sim + 1.0) / 2.0 def batch_cosine_similarity( query: np.ndarray, corpus: np.ndarray ) -> np.ndarray: """ Compute cosine similarity of query against entire corpus in one shot. query: shape (D,) corpus: shape (N, D) Returns: shape (N,) with scores in [-1, 1] At 100k candidates (D=384): ~10ms on CPU. """ return corpus @ query