claude-smart 0.2.42 → 0.2.44

package/plugin/vendor/reflexio/reflexio/server/llm/providers/local_embedding_provider.py

@@ -0,0 +1,213 @@
+"""Local in-process embedder using Chroma's ONNX all-MiniLM-L6-v2.
+
+Lets reflexio run without any external embedding API key. Activation is
+opt-in via ``CLAUDE_SMART_USE_LOCAL_EMBEDDING=1`` and requires the
+``chromadb`` pip package to be installed (we re-use its packaged ONNX
+model + tokenizer rather than re-bundling them).
+
+The model natively produces 384-dim vectors; reflexio's storage schema
+expects 512 dims (``EMBEDDING_DIMENSIONS`` in the vec0 virtual tables).
+We zero-pad each vector to 512 inside this module so the rest of
+reflexio is unchanged. Cosine similarity is preserved on the 384-dim
+subspace — safe as long as *all* embeddings in a given DB come from
+this provider (mixing providers has always required a DB wipe).
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import logging
+import os
+import threading
+from typing import Any
+
+_LOGGER = logging.getLogger(__name__)
+
+_ENV_ENABLE = "CLAUDE_SMART_USE_LOCAL_EMBEDDING"
+_MODEL_KEY = "local/minilm-l6-v2"
+
+# Reflexio's storage schema (vec0 virtual tables) expects this dimension.
+# MiniLM-L6-v2 natively produces 384; we pad with zeros to _TARGET_DIM.
+_NATIVE_DIM = 384
+_TARGET_DIM = 512
+
+# Conservative character budget to stay under MiniLM's 256-token hard cap.
+# ~4 chars/token in English prose; leave headroom so we never raise the
+# ValueError that ONNXMiniLM_L6_V2 throws on over-length input.
+_MAX_CHARS = 800
+
+
+class LocalEmbedderError(RuntimeError):
+    """Raised when the local embedder is called without chromadb installed."""
+
+
+class LocalEmbedder:
+    """Lazily-loaded singleton wrapping Chroma's ONNXMiniLM_L6_V2."""
+
+    _instance: LocalEmbedder | None = None
+    _lock = threading.Lock()
+
+    def __init__(self) -> None:
+        self._ef: Any | None = None
+        self._ef_lock = threading.Lock()
+
+    @classmethod
+    def get(cls) -> LocalEmbedder:
+        """Return the process-wide singleton, constructing it on first use."""
+        if cls._instance is None:
+            with cls._lock:
+                if cls._instance is None:
+                    cls._instance = cls()
+        return cls._instance
+
+    def _load(self) -> Any:
+        """Lazy-import and instantiate the ONNX embedding function."""
+        if self._ef is not None:
+            return self._ef
+        with self._ef_lock:
+            if self._ef is not None:
+                return self._ef
+            try:
+                from chromadb.utils.embedding_functions import (  # type: ignore[import-not-found]
+                    ONNXMiniLM_L6_V2,
+                )
+            except ImportError as exc:
+                raise LocalEmbedderError(
+                    f"{_ENV_ENABLE}=1 but `chromadb` is not installed. "
+                    "Install with `uv add chromadb` or `pip install chromadb`."
+                ) from exc
+            self._ef = ONNXMiniLM_L6_V2()
+            _LOGGER.info(
+                "Initialized local ONNX embedder (model=%s, cache=%s)",
+                ONNXMiniLM_L6_V2.MODEL_NAME,
+                ONNXMiniLM_L6_V2.DOWNLOAD_PATH,
+            )
+            return self._ef
+
+    def embed(self, texts: list[str]) -> list[list[float]]:
+        """Embed a batch of documents, returning 512-dim padded vectors.
+
+        Args:
+            texts: Documents to embed. Each is truncated to ``_MAX_CHARS``
+                characters to stay under the 256-token cap of MiniLM-L6-v2.
+
+        Returns:
+            list[list[float]]: One vector per input, each exactly
+                ``_TARGET_DIM`` (512) floats with the last 128 positions
+                zero-padded.
+        """
+        ef = self._load()
+        safe_inputs = [(text or "")[:_MAX_CHARS] for text in texts]
+        raw = ef(safe_inputs)
+        return [_pad(vec) for vec in raw]
+
+
+def _pad(vec: Any) -> list[float]:
+    """Zero-pad a 384-dim vector to ``_TARGET_DIM`` as a plain list[float]."""
+    as_list = list(vec) if not isinstance(vec, list) else vec
+    floats = [float(x) for x in as_list]
+    if len(floats) == _TARGET_DIM:
+        return floats
+    if len(floats) > _TARGET_DIM:
+        return floats[:_TARGET_DIM]
+    return floats + [0.0] * (_TARGET_DIM - len(floats))
+
+
+_REGISTERED = False
+
+
+def is_chromadb_importable() -> bool:
+    """Return True when the ``chromadb`` package is importable.
+
+    Independent of :data:`_ENV_ENABLE` (``CLAUDE_SMART_USE_LOCAL_EMBEDDING``).
+    Used by callers that want to know whether the local fallback is
+    *possible* regardless of whether claude-smart has explicitly opted in.
+
+    Returns:
+        bool: True if ``importlib.util.find_spec("chromadb")`` finds the
+            package, False otherwise.
+    """
+    return importlib.util.find_spec("chromadb") is not None
+
+
+def register_if_chromadb_available() -> bool:
+    """Make the local embedder available whenever ``chromadb`` imports.
+
+    This is the env-var-independent companion to
+    :func:`register_if_enabled`. Called once from ``litellm_client`` at
+    module import so the local-embedder dispatch is wired up regardless
+    of whether claude-smart's opt-in env var is set. Idempotent — safe
+    to call more than once per process.
+
+    The actual routing is done by a prefix check in
+    ``LiteLLMClient.get_embedding(s)``; this function's job is to
+    eagerly probe for ``chromadb`` and log a clear message.
+
+    Returns:
+        bool: True if the embedder is usable after this call, False
+            when ``chromadb`` is not importable.
+    """
+    global _REGISTERED
+    if _REGISTERED:
+        return True
+    if not is_chromadb_importable():
+        _LOGGER.debug("Local embedder not registered: `chromadb` is not installed.")
+        return False
+    _REGISTERED = True
+    _LOGGER.debug("Registered local MiniLM embedding handler (model=%s)", _MODEL_KEY)
+    return True
+
+
+def register_if_enabled() -> bool:
+    """Backwards-compatible alias for :func:`register_if_chromadb_available`.
+
+    Historically gated on ``CLAUDE_SMART_USE_LOCAL_EMBEDDING=1``; now
+    delegates to the chromadb-only check so the local embedder is also
+    available as a silent fallback when no cloud embedder is configured.
+    The claude-smart opt-in env var continues to drive
+    :func:`is_local_embedder_available` (provider-priority ordering),
+    which is the public contract the env var actually owns.
+
+    Returns:
+        bool: True if the embedder is usable after this call, False
+            otherwise.
+    """
+    return register_if_chromadb_available()
+
+
+def is_enabled() -> bool:
+    """Return True when a previous registration call has succeeded.
+
+    Returns:
+        bool: True if the provider is currently registered and usable in
+            this process, False otherwise.
+    """
+    return _REGISTERED
+
+
+def is_local_embedder_available() -> bool:
+    """Return True iff both the env flag is set and ``chromadb`` imports.
+
+    Unlike :func:`is_enabled`, this does not require
+    :func:`register_if_enabled` to have run. It is the predicate
+    ``model_defaults.detect_available_providers`` uses to decide whether
+    to surface ``"local"`` as an option.
+
+    Returns:
+        bool: True when ``CLAUDE_SMART_USE_LOCAL_EMBEDDING=1``
+            AND ``chromadb`` is importable.
+    """
+    if os.environ.get(_ENV_ENABLE) != "1":
+        return False
+    return is_chromadb_importable()
+
+
+__all__ = [
+    "LocalEmbedder",
+    "LocalEmbedderError",
+    "is_chromadb_importable",
+    "is_enabled",
+    "is_local_embedder_available",
+    "register_if_chromadb_available",
+    "register_if_enabled",
+]

package/plugin/vendor/reflexio/reflexio/server/llm/providers/nomic_embedding_provider.py

@@ -0,0 +1,288 @@
+"""Local in-process embedder using ``nomic-ai/nomic-embed-text-v1.5``.
+
+A higher-quality alternative to the chromadb-bundled MiniLM-L6-v2: 137M
+parameters, 768-dim native, supports Matryoshka representation (64–768
+dimensions without retraining), 8192-token context, Apache-2.0 licensed.
+Performs comparably to OpenAI's ``text-embedding-3-small`` on MTEB
+retrieval at a fraction of the latency cost when run locally on CPU or
+Apple Silicon.
+
+Activation
+----------
+
+- Set ``CLAUDE_SMART_USE_LOCAL_EMBEDDING=1`` in the process environment.
+- Pass model name ``local/nomic-embed-v1.5`` (or ``local/nomic-embed-text-v1.5``)
+  to :func:`LiteLLMClient.get_embedding`/``get_embeddings``.
+- Requires the ``sentence-transformers`` pip dependency.
+
+Storage compatibility
+---------------------
+
+Reflexio's vec0 tables expect 512-dim vectors (``EMBEDDING_DIMENSIONS``).
+Nomic's native 768 dim is reduced via Matryoshka — slice the first 512
+floats, then re-normalize to unit length so cosine similarity remains
+comparable. Quality on retrieval tasks at 512 dim is ~95% of the full
+768 (per Nomic's own evaluation).
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import logging
+import math
+import os
+import threading
+from typing import Any
+
+from reflexio.server.llm.llm_utils import positive_int_env
+
+_LOGGER = logging.getLogger(__name__)
+
+_ENV_ENABLE = "CLAUDE_SMART_USE_LOCAL_EMBEDDING"
+_ENV_PROVIDER = "REFLEXIO_EMBEDDING_PROVIDER"
+_ENV_DAEMON = "REFLEXIO_EMBEDDING_DAEMON"
+_MODEL_KEYS = {"local/nomic-embed-v1.5", "local/nomic-embed-text-v1.5"}
+_HF_MODEL_NAME = "nomic-ai/nomic-embed-text-v1.5"
+
+# Reflexio's vec0 schema dim. Nomic v1.5 outputs 768 natively; we slice
+# to 512 (Matryoshka) and re-normalize.
+_TARGET_DIM = 512
+# Nomic v1.5 was trained with task-prefixed inputs; "search_document"
+# vs "search_query" prefixes give better asymmetric retrieval. Reflexio's
+# storage layer already passes a "search_document: " / "search_query: "
+# prefix when calling _get_embedding(purpose=...), so we don't add another
+# prefix here — the input arrives correctly tagged.
+# The model has a 8192 token context window; we still cap chars
+# defensively to avoid pathological multi-MB inputs.
+_MAX_CHARS = 32_000
+
+# Encode in small mini-batches so a single large request can't spike memory:
+# peak activation memory scales with batch_size, not with the total number of
+# texts in the request. A small batch is what makes the daemon's bounded
+# concurrency (see ``embedding_service``) safe to raise above 1.
+_DEFAULT_ENCODE_BATCH_SIZE = 4
+_ENV_BATCH_SIZE = "REFLEXIO_EMBED_BATCH_SIZE"
+
+
+def _encode_batch_size() -> int:
+    """Resolve the encode mini-batch size from env, defaulting to 4."""
+    return positive_int_env(_ENV_BATCH_SIZE, _DEFAULT_ENCODE_BATCH_SIZE, _LOGGER)
+
+
+class NomicEmbedderError(RuntimeError):
+    """Raised when the Nomic embedder is requested but its deps are missing."""
+
+
+def _huggingface_cache_path() -> str:
+    return os.environ.get("HF_HOME") or "~/.cache/huggingface"
+
+
+class NomicEmbedder:
+    """Lazily-loaded singleton wrapping a sentence-transformers model.
+
+    Loading the underlying ``nomic-embed-text-v1.5`` model takes ~5–10 s on
+    first call (downloads ~550 MB on cold start, then cached under
+    ``~/.cache/huggingface/``). After that, embedding latency on CPU is
+    ~30–60 ms per single text and ~200 ms per batch of 32 (Apple M-series).
+    """
+
+    _instance: NomicEmbedder | None = None
+    _lock = threading.Lock()
+
+    def __init__(self) -> None:
+        self._model: Any | None = None
+        self._model_lock = threading.Lock()
+
+    @classmethod
+    def get(cls) -> NomicEmbedder:
+        """Return the process-wide singleton, constructing it on first use."""
+        if cls._instance is None:
+            with cls._lock:
+                if cls._instance is None:
+                    cls._instance = cls()
+        return cls._instance
+
+    def _load(self) -> Any:
+        """Lazy-import sentence-transformers and load the Nomic model."""
+        if self._model is not None:
+            return self._model
+        with self._model_lock:
+            if self._model is not None:
+                return self._model
+            try:
+                from sentence_transformers import (
+                    SentenceTransformer,  # type: ignore[import-not-found]
+                )
+            except ImportError as exc:
+                raise NomicEmbedderError(
+                    "sentence-transformers is required for the Nomic local "
+                    "embedder. Install with `uv add sentence-transformers`."
+                ) from exc
+            _LOGGER.info(
+                "Loading Nomic embedding model %s — first call may download "
+                "~550 MB to %s",
+                _HF_MODEL_NAME,
+                _huggingface_cache_path(),
+            )
+            # Force CPU device — MPS init has been observed to hang on some
+            # Apple Silicon + macOS combos for several minutes during model
+            # load. CPU is fast enough for our use case (137M params) and
+            # behaves predictably. Set NOMIC_EMBED_DEVICE=mps|cuda|cpu to
+            # override.
+            device = os.environ.get("NOMIC_EMBED_DEVICE", "cpu")
+            self._model = SentenceTransformer(
+                _HF_MODEL_NAME,
+                trust_remote_code=True,  # Nomic v1.5 ships custom code
+                device=device,
+            )
+            _LOGGER.info(
+                "Nomic embedder ready (model=%s, target_dim=%d, native_dim=%d)",
+                _HF_MODEL_NAME,
+                _TARGET_DIM,
+                _embedding_dimension(self._model),
+            )
+            return self._model
+
+    def embed(self, texts: list[str]) -> list[list[float]]:
+        """Embed a batch of texts, returning ``_TARGET_DIM``-sized unit vectors.
+
+        Args:
+            texts: Inputs to encode. Each is char-truncated to ``_MAX_CHARS``
+                as a defensive cap; Nomic itself supports 8192 tokens.
+
+        Returns:
+            list[list[float]]: One vector per input, each exactly
+                ``_TARGET_DIM`` (512) floats and L2-normalised so cosine
+                similarity equals dot product.
+        """
+        model = self._load()
+        safe = [(t or "")[:_MAX_CHARS] for t in texts]
+        # show_progress_bar=False so server logs stay clean during ingest
+        # batches. convert_to_numpy=True returns a numpy ndarray; we slice
+        # and renormalise per-row before converting to plain Python lists.
+        raw = model.encode(
+            safe,
+            batch_size=_encode_batch_size(),
+            show_progress_bar=False,
+            convert_to_numpy=True,
+        )
+        return [_truncate_and_renormalise(vec.tolist()) for vec in raw]
+
+
+def _truncate_and_renormalise(vec: list[float]) -> list[float]:
+    """Slice to ``_TARGET_DIM`` and L2-renormalise for valid Matryoshka use.
+
+    Args:
+        vec (list[float]): Native-dim Nomic embedding (typically 768 floats,
+            already L2-unit on the full 768).
+
+    Returns:
+        list[float]: Exactly ``_TARGET_DIM`` floats, L2-normalised in the
+            truncated subspace so cosine similarity remains a valid metric.
+            Zero-padded if the input is shorter than ``_TARGET_DIM``.
+    """
+    if len(vec) >= _TARGET_DIM:
+        sliced = vec[:_TARGET_DIM]
+    else:
+        sliced = vec + [0.0] * (_TARGET_DIM - len(vec))
+    norm = math.sqrt(sum(x * x for x in sliced))
+    if norm <= 0:
+        return sliced
+    return [x / norm for x in sliced]
+
+
+def _embedding_dimension(model: Any) -> int:
+    get_embedding_dimension = getattr(model, "get_embedding_dimension", None)
+    if callable(get_embedding_dimension):
+        dimension = get_embedding_dimension()
+    else:
+        dimension = model.get_sentence_embedding_dimension()
+    return int(dimension)  # type: ignore[arg-type]
+
+
+_REGISTERED = False
+
+
+def register_if_enabled() -> bool:
+    """Make the Nomic embedder available when env + deps allow it.
+
+    Idempotent. Returns ``True`` when the embedder is usable after this
+    call. Routing happens via prefix-match on the model name in
+    ``LiteLLMClient.get_embedding(s)``.
+
+    Eagerly pre-warms the model in a daemon thread so the first request
+    doesn't pay the ~30 s cold-start cost. The thread is fire-and-forget;
+    callers either land mid-load (and block briefly) or after-load (and
+    proceed immediately).
+    """
+    global _REGISTERED
+    if _REGISTERED:
+        return True
+    if os.environ.get(_ENV_ENABLE) != "1":
+        return False
+    provider = os.environ.get(_ENV_PROVIDER, "").strip().lower()
+    if provider in {"local_service", "internal_service", "off"}:
+        _LOGGER.info(
+            "Nomic in-process prewarm skipped because %s=%s",
+            _ENV_PROVIDER,
+            provider,
+        )
+        return False
+    if not provider and os.environ.get(_ENV_DAEMON) != "1":
+        _LOGGER.info(
+            "Nomic in-process prewarm skipped; %s=1 now defaults to the "
+            "shared embedding service.",
+            _ENV_ENABLE,
+        )
+        return False
+    if importlib.util.find_spec("sentence_transformers") is None:
+        _LOGGER.warning(
+            "%s=1 set but `sentence-transformers` not installed; the Nomic "
+            "local embedder will not be available.",
+            _ENV_ENABLE,
+        )
+        return False
+    _REGISTERED = True
+    _LOGGER.info(
+        "Nomic local embedding provider enabled (models=%s)", sorted(_MODEL_KEYS)
+    )
+
+    def _prewarm() -> None:
+        """Background load + dummy inference so the first real request is fast."""
+        try:
+            embedder = NomicEmbedder.get()
+            embedder.embed(["warmup"])
+            _LOGGER.info("Nomic embedder pre-warmed")
+        except Exception:  # noqa: BLE001
+            _LOGGER.exception(
+                "Nomic embedder pre-warm failed; first call will pay the cost"
+            )
+
+    threading.Thread(target=_prewarm, daemon=True, name="nomic-prewarm").start()
+    return True
+
+
+def is_enabled() -> bool:
+    """Return True after a successful :func:`register_if_enabled`."""
+    return _REGISTERED
+
+
+def is_nomic_model(model: str) -> bool:
+    """Predicate used by ``LiteLLMClient`` to route by model name.
+
+    Args:
+        model (str): The embedding model name passed by the caller.
+
+    Returns:
+        bool: True when the model resolves to the Nomic provider.
+    """
+    return model in _MODEL_KEYS
+
+
+__all__ = [
+    "NomicEmbedder",
+    "NomicEmbedderError",
+    "is_enabled",
+    "is_nomic_model",
+    "register_if_enabled",
+]

package/plugin/vendor/reflexio/reflexio/server/llm/rerank/__init__.py

@@ -0,0 +1,6 @@
+"""Reranking helpers — local cross-encoder + LLM relevance judge."""
+
+from reflexio.server.llm.rerank.cross_encoder_reranker import prewarm, score_pairs
+from reflexio.server.llm.rerank.llm_reranker import score_pairs_llm
+
+__all__ = ["prewarm", "score_pairs", "score_pairs_llm"]

package/plugin/vendor/reflexio/reflexio/server/llm/rerank/cross_encoder_reranker.py

@@ -0,0 +1,187 @@
+"""Local cross-encoder reranker for ``(query, document)`` pairs.
+
+Wraps ``cross-encoder/ms-marco-MiniLM-L-6-v2`` (~25M params) from
+``sentence-transformers``. The model is lazy-loaded on first call and
+held as a process-wide singleton — load takes ~3 s but only happens
+once per server start. Scoring K=30 pairs takes ~50 ms on CPU.
+
+Usage
+-----
+
+>>> from reflexio.server.llm.rerank import score_pairs
+>>> scores = score_pairs("italian food", ["pasta lover", "weather report"])
+>>> scores[0] > scores[1]
+True
+
+The helper is intentionally side-effect free at import time: building
+the singleton happens only when ``score_pairs`` is called, so importing
+this module never triggers a model download.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import threading
+from typing import Any
+
+_LOGGER = logging.getLogger(__name__)
+
+# HuggingFace identifier for the cross-encoder. Chosen for the
+# size/quality trade-off: 22M parameters, ~50 ms for K=30 on CPU,
+# well-known MS-MARCO benchmark performance.
+_MODEL_NAME = "cross-encoder/ms-marco-MiniLM-L-6-v2"
+
+# Device override for the cross-encoder. Defaults to CPU: without an
+# explicit device sentence-transformers auto-selects MPS on Apple
+# Silicon, where torch's caching allocator accumulates gigabytes of
+# GPU buffers it never returns to the OS — and the 22M-param model
+# gains nothing from GPU at K=30 pairs. Mirrors NOMIC_EMBED_DEVICE.
+_DEVICE_ENV_VAR = "REFLEXIO_RERANK_DEVICE"
+
+# Singleton state — never accessed directly outside ``_get_model``.
+_MODEL: Any | None = None
+_MODEL_LOCK = threading.Lock()
+
+
+class CrossEncoderUnavailableError(RuntimeError):
+    """Raised when the cross-encoder model cannot be loaded.
+
+    The most common cause is ``sentence-transformers`` being absent from
+    the runtime environment. Callers should treat this as a soft failure
+    (log + skip rerank) rather than a 500.
+    """
+
+
+def _import_cross_encoder() -> Any:
+    """Robustly import ``sentence_transformers.CrossEncoder``.
+
+    The ``sentence_transformers`` package is loaded both by the Nomic
+    local-embedding pre-warm thread (kicked off by ``LiteLLMClient.__init__``
+    when ``CLAUDE_SMART_USE_LOCAL_EMBEDDING=1``) and by this reranker. When
+    those concurrent imports race, one thread can see a half-loaded
+    ``sentence_transformers`` module in ``sys.modules`` whose ``CrossEncoder``
+    attribute was never bound — Python's import machinery hands back the
+    partial module without re-running ``__init__``. This helper detects that
+    case, drops the stale entry, and re-imports cleanly.
+
+    Returns:
+        Any: The ``CrossEncoder`` class.
+
+    Raises:
+        CrossEncoderUnavailableError: When the package genuinely isn't
+            installed, or every retry yields a partial module.
+    """
+    import sys
+
+    for _attempt in range(2):
+        try:
+            from sentence_transformers import CrossEncoder
+        except ImportError:
+            # Partial import — drop the stale entry and try once more.
+            sys.modules.pop("sentence_transformers", None)
+            continue
+        return CrossEncoder
+    try:
+        from sentence_transformers import (
+            CrossEncoder,  # noqa: F401 — final attempt for the error path
+        )
+    except ImportError as e:
+        raise CrossEncoderUnavailableError(
+            "sentence-transformers is not installed; cannot use the "
+            "cross-encoder reranker"
+        ) from e
+    return CrossEncoder
+
+
+def _get_model() -> Any:
+    """Return the lazy-loaded cross-encoder singleton.
+
+    The first caller pays the load cost (~3 s, weights cached under
+    ``~/.cache/huggingface/`` after first download). Subsequent callers
+    get the warm instance immediately.
+
+    Returns:
+        Any: A ``sentence_transformers.CrossEncoder`` instance.
+
+    Raises:
+        CrossEncoderUnavailableError: If ``sentence-transformers`` is not
+            importable, or if the underlying model fails to load.
+    """
+    global _MODEL  # noqa: PLW0603 — singleton-pattern intentional
+    if _MODEL is not None:
+        return _MODEL
+    with _MODEL_LOCK:
+        if _MODEL is not None:
+            return _MODEL
+        cross_encoder_cls = _import_cross_encoder()
+        device = os.environ.get(_DEVICE_ENV_VAR, "cpu")
+        try:
+            _LOGGER.info("Loading reranker model %s (device=%s)", _MODEL_NAME, device)
+            _MODEL = cross_encoder_cls(_MODEL_NAME, device=device)
+        except Exception as e:  # noqa: BLE001 — surface as a typed failure
+            raise CrossEncoderUnavailableError(
+                f"Failed to load cross-encoder model {_MODEL_NAME!r}: {e}"
+            ) from e
+        _LOGGER.info("Reranker model ready (model=%s)", _MODEL_NAME)
+        return _MODEL
+
+
+def score_pairs(query: str, docs: list[str]) -> list[float]:
+    """Score ``(query, doc)`` pairs with the cross-encoder.
+
+    Higher score means more relevant. Scores are not bounded to a fixed
+    range — they are raw model logits — so callers should treat them as
+    opaque relative-ranking signal, not as probabilities.
+
+    Args:
+        query (str): The reranking query.
+        docs (list[str]): Documents to score against ``query``.
+
+    Returns:
+        list[float]: One score per document, in the same order as
+            ``docs``. Empty list when ``docs`` is empty.
+
+    Raises:
+        CrossEncoderUnavailableError: If the cross-encoder cannot be
+            loaded (re-raised from :func:`_get_model`).
+    """
+    if not docs:
+        return []
+    model = _get_model()
+    pairs = [(query, doc) for doc in docs]
+    raw_scores = model.predict(pairs, show_progress_bar=False)
+    # ``predict`` returns a numpy array; convert to plain Python floats so
+    # the caller can serialise the result without numpy as a dependency.
+    return [float(s) for s in raw_scores]
+
+
+def prewarm() -> bool:
+    """Force the cross-encoder model to load at startup.
+
+    Call once during app startup so the ~3s model load never lands on a user
+    query (and never serializes a concurrent burst behind the model lock).
+    Never raises — startup must not crash if the cross-encoder is unavailable
+    or fails to score the smoke input.
+
+    Returns:
+        True if the model loaded and scored a smoke input; False otherwise
+        (callers should treat the floor as degraded, not crash).
+    """
+    try:
+        score_pairs("warmup", ["warmup"])
+    except CrossEncoderUnavailableError:
+        _LOGGER.warning(
+            "Cross-encoder unavailable at startup; relevance floor will degrade "
+            "to unfiltered results until the model is available."
+        )
+        return False
+    except Exception:  # noqa: BLE001 — pre-warm must never crash startup
+        _LOGGER.warning(
+            "Cross-encoder pre-warm failed unexpectedly; relevance floor will "
+            "degrade to unfiltered results until the model is available.",
+            exc_info=True,
+        )
+        return False
+    _LOGGER.info("Cross-encoder pre-warmed.")
+    return True