Skip to content

~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.

perf(rag): skip dimension probe on search paths (#5284)

LearningCircuit4720e696fbfc
diff --git a/changelog.d/5284.misc.md b/changelog.d/5284.misc.md
new file mode 100644
index 0000000000..dcd300a31d
--- /dev/null
+++ b/changelog.d/5284.misc.md
@@ -0,0 +1 @@
+Library searches skip the redundant embedding-dimension probe for faster RAG lookups, while still rejecting queries whose vector dimensions don't match the index — or whose embedding is otherwise degenerate (non-finite, zero-magnitude, or overflow-magnitude) — including when the index is empty; a refused query now raises rather than silently returning no results.
diff --git a/src/local_deep_research/research_library/services/library_rag_service.py b/src/local_deep_research/research_library/services/library_rag_service.py
index 6d761f1041..857f047bf4 100644
--- a/src/local_deep_research/research_library/services/library_rag_service.py
+++ b/src/local_deep_research/research_library/services/library_rag_service.py
@@ -12,6 +12,7 @@ Handles indexing and searching library documents using RAG:
import threading
import time
import json
+import re
from contextlib import contextmanager
from dataclasses import dataclass
from datetime import datetime, UTC
@@ -213,6 +214,30 @@ _QUARANTINE_SUFFIX_RETRY_CAP = 32
# to inspect / submit with a bug report; anything older is dropped.
_QUARANTINE_KEEP_RECENT = 5
+# ``FaissVectorStore._prepare`` raises ``ValueError`` with one of these exact,
+# fixed-text messages when it refuses a query vector for a reason OTHER than
+# a dimension mismatch (that one varies by dimension, so it stays a regex in
+# ``search()`` below): non-finite (NaN/Inf), zero/overflow magnitude under L2
+# normalization, and raw magnitude too large for unnormalized float32
+# distance math. ``search()`` matches these verbatim (copied from
+# ``_prepare``, not derived from it) so an unrelated provider ``ValueError``
+# that merely resembles one of them keeps passing through unchanged — same
+# fail-open-by-default posture as the dimension regex.
+_DEGENERATE_QUERY_VECTOR_MESSAGES = frozenset(
+ {
+ "vectors contain non-finite values (NaN/Inf) — bad embedding",
+ (
+ "vectors contain a zero-magnitude or overflow-magnitude row "
+ "that L2 normalization cannot represent — bad embedding"
+ ),
+ (
+ "vectors contain a magnitude too large for float32 distance "
+ "computation (would overflow to a dropped/mis-ranked search "
+ "hit) — normalize the embeddings or use a bounded model"
+ ),
+ }
+)
+
def _get_faiss_write_lock(username: str, index_path: str) -> _TrackedRLock:
"""Return the lock for ``(username, index_path)``, creating it on first
@@ -1125,6 +1150,7 @@ class LibraryRAGService:
rag_index: RAGIndex,
*,
reset_stale_state: bool = False,
+ probe_dimension: bool | None = None,
) -> Path:
"""Verify -> quarantine -> dimension-check pre-flight for ``rag_index``.
@@ -1137,6 +1163,17 @@ class LibraryRAGService:
that read ``self.rag_index_record`` afterwards see the current
values — and returns the resolved on-disk path.
+ ``probe_dimension`` decides whether the embedding-dimension drift
+ probe runs (see the ``verified and should_probe_dimension`` block
+ below). ``None`` (the default) keeps the original rule — probe iff
+ ``reset_stale_state`` (a WRITE path). Pass an explicit ``True``/
+ ``False`` to override that rule for a call site that is not itself
+ a write but still needs (or must skip) the probe — e.g.
+ ``reconcile_collection_index`` passes ``True``: unlike ``search()``,
+ it never embeds a query, so it gets no free dimension check from
+ the vector store's ``_prepare`` and would otherwise miss drift
+ entirely.
+
Deliberately does NOT load or construct a vector store: that stays
the caller's job (via ``VectorIndex(...)``), so a corrupt/foreign/
dimension-mismatched file surfaces as an exception from THAT
@@ -1191,10 +1228,11 @@ class LibraryRAGService:
related_entity_type="rag_index",
related_entity_id=rag_index.id,
)
- # Adopted = now trusted: fall through to the SAME
- # embedding-dimension-drift probe the verified branch
- # runs, so an adopted index whose model dimension changed
- # is rebuilt rather than silently mismatched at add time.
+ # Adopted = now trusted: fall through — a WRITE
+ # path (reset_stale_state=True) then probes the
+ # embedding dimension and rebuilds on drift; a READ
+ # path skips the probe (the vector store's
+ # ``_prepare`` rejects a wrong-dimension query).
verified = True
elif not reset_stale_state:
# Read path (search): refuse to serve an index that
@@ -1229,13 +1267,27 @@ class LibraryRAGService:
f"new index."
)
self._quarantine_corrupt_index(index_path, reason)
- if verified:
+ should_probe_dimension = (
+ reset_stale_state
+ if probe_dimension is None
+ else probe_dimension
+ )
+ if verified and should_probe_dimension:
# Probe the embedding model OUTSIDE the quarantine
- # decision: embed_query fails when the provider itself
- # is unreachable (e.g. Ollama down), which says nothing
- # about the index file's health, and must propagate
- # rather than trigger a destructive rebuild of a
- # healthy index.
+ # decision (WRITE paths only, by default): embed_query
+ # fails when the provider itself is unreachable (e.g.
+ # Ollama down), which says nothing about the index
+ # file's health, and must propagate rather than trigger
+ # a destructive rebuild of a healthy index. search()
+ # skips the probe entirely — a wrong-dimension query is
+ # rejected by the vector store's ``_prepare`` (see
+ # FaissVectorStore) so reads stay fail-closed without
+ # the round-trip. ``reconcile_collection_index`` is the
+ # one exception: it never embeds a query (it only calls
+ # ``live_ids()``), so it gets none of that free
+ # protection from ``_prepare`` — it passes
+ # ``probe_dimension=True`` explicitly to keep detecting
+ # drift despite ``reset_stale_state=False``.
current_dim = len(
self.embedding_manager.embeddings.embed_query(
"dimension_check"
@@ -1243,16 +1295,6 @@ class LibraryRAGService:
)
stored_dim = rag_index.embedding_dimension
if stored_dim and current_dim != stored_dim:
- if not reset_stale_state:
- # Read path: surface the mismatch instead of
- # deleting the index + wiping DB state (which a mere
- # search must never do). A write/index operation
- # owns the destructive rebuild.
- raise RuntimeError(
- f"Embedding dimension mismatch for {index_path}: "
- f"index dim={stored_dim}, model dim="
- f"{current_dim} — refusing on a read path"
- )
logger.warning(
f"Embedding dimension mismatch detected! "
f"Index created with dim={stored_dim}, "
@@ -1347,6 +1389,7 @@ class LibraryRAGService:
collection_name: str,
*,
reset_stale_state: bool = False,
+ probe_dimension: bool | None = None,
) -> VectorIndex:
"""Build a :class:`VectorIndex` for ``collection_id``.
@@ -1364,6 +1407,10 @@ class LibraryRAGService:
— callers on a delete-only path that must not create an index
(e.g. ``remove_documents_from_index``) guard with their own
existence check before calling this.
+
+ ``probe_dimension`` is forwarded to ``_preflight_index_path`` (see
+ its docstring) unchanged. Every caller but
+ ``reconcile_collection_index`` leaves it at the default ``None``.
"""
# Only WRITE paths (reset_stale_state=True) may re-promote a reused
# index to is_current; a read-path search must not flip the pointer.
@@ -1372,7 +1419,10 @@ class LibraryRAGService:
)
self.rag_index_record = rag_index
index_path = self._preflight_index_path(
- collection_id, rag_index, reset_stale_state=reset_stale_state
+ collection_id,
+ rag_index,
+ reset_stale_state=reset_stale_state,
+ probe_dimension=probe_dimension,
)
lock = _get_faiss_write_lock(self.username, str(index_path))
@@ -1478,22 +1528,67 @@ class LibraryRAGService:
) -> List[SearchResult]:
"""Semantic search within ``collection_id`` via the vector store.
- Runs the same verify/quarantine/dimension pre-flight as indexing
- (through ``_get_vector_index``), then delegates to
- ``VectorIndex.search``. ``reset_stale_state`` is left at its
- default False — this is a read path: a transient integrity hiccup
- during a mere search must not wipe the collection's indexed state
- and force a full re-embed.
+ Runs the same verify/quarantine pre-flight as indexing (through
+ ``_get_vector_index``), then delegates to ``VectorIndex.search``.
+ The embedding-dimension drift probe is SKIPPED on this read path:
+ the vector store's ``_prepare`` (see FaissVectorStore) rejects a
+ wrong-dimension, non-finite, zero-magnitude, or overflow-magnitude
+ query vector before it ever reaches the FAISS index — even on an
+ EMPTY store, since ``_prepare`` runs before the ``ntotal == 0``
+ check. Reads stay fail-closed without the probe's round-trip.
+ Every such rejection is translated below into a service-level
+ ``RuntimeError`` carrying the collection id: a degenerate or
+ wrong-dimension query embedding is a PROVIDER fault worth surfacing
+ loudly, not one to silently swallow. ``reset_stale_state`` is left
+ at its default False: a transient integrity hiccup during a mere
+ search must not wipe the collection's indexed state and force a
+ full re-embed.
Callers are expected to have already confirmed the collection has
indexed documents (e.g. via ``get_rag_stats``) before calling this
- — this method will otherwise create an empty RAGIndex/store for a
- never-indexed (collection, embedding model) pair and return no
- results, rather than raising.
+ — for an ORDINARY query, this method will otherwise create an empty
+ RAGIndex/store for a never-indexed (collection, embedding model)
+ pair and return no results, rather than raising. A DEGENERATE query
+ embedding (see above) is refused even on that never-indexed store —
+ it is never swallowed into an empty result either.
"""
collection_name = f"collection_{collection_id}"
vindex = self._get_vector_index(collection_id, collection_name)
- return vindex.search(query, top_k)
+ try:
+ return vindex.search(query, top_k)
+ except ValueError as exc:
+ # _prepare() in FaissVectorStore raises ValueError when it
+ # refuses the query vector outright: either a dimension
+ # mismatch (both dimensions in the message, so it needs a
+ # regex — see below) or one of the fixed-text "degenerate
+ # embedding" messages in _DEGENERATE_QUERY_VECTOR_MESSAGES
+ # above (non-finite, zero/overflow magnitude). Matching the
+ # exact formats (not a substring/keyword check) means an
+ # unrelated provider ValueError that merely mentions
+ # "dimension" or "magnitude" still passes through unchanged.
+ # Translate every match to a service-level RuntimeError with
+ # collection context so callers that catch the legacy
+ # exception type, and logs that report the affected
+ # collection, still work.
+ msg = str(exc)
+ if re.fullmatch(
+ r"vector dimension [0-9]+ != index dimension [0-9]+", msg
+ ):
+ raise RuntimeError(
+ f"Embedding dimension mismatch — the index for "
+ f"collection {collection_id} was built with a different "
+ f"embedding model. Re-index the collection to fix this. "
+ f"(underlying error: {exc})"
+ ) from exc
+ if msg in _DEGENERATE_QUERY_VECTOR_MESSAGES:
+ raise RuntimeError(
+ f"Query embedding rejected for collection "
+ f"{collection_id}: the embedding provider returned a "
+ f"degenerate vector for this query (non-finite, "
+ f"zero-magnitude, or overflow-magnitude) that cannot be "
+ f"searched. (underlying error: {exc})"
+ ) from exc
+ raise
def get_current_index_info(
self, collection_id: Optional[str] = None
@@ -3069,7 +3164,19 @@ class LibraryRAGService:
collection_name = f"collection_{collection_id}"
with self._collection_transaction_lock(collection_id):
vindex = self._get_vector_index(
- collection_id, collection_name, reset_stale_state=False
+ collection_id,
+ collection_name,
+ reset_stale_state=False,
+ # This call site never embeds a query — it only calls
+ # ``live_ids()`` below — so it gets none of the fail-closed
+ # dimension check a real search gets for free from
+ # ``FaissVectorStore._prepare``. Without explicitly opting
+ # back in here, an embedding-model dimension drift would go
+ # completely undetected: the file still loads (its stored
+ # ``dimension`` came from the DB row, which always matches
+ # ``index.d``), and a non-empty live index means the
+ # refuse-to-shrink guard below never fires either.
+ probe_dimension=True,
)
live_ids = set(vindex.live_ids())
rag_index_id = self.rag_index_record.id
diff --git a/src/local_deep_research/vector_stores/implementations/faiss_store.py b/src/local_deep_research/vector_stores/implementations/faiss_store.py
index ce0d4f763c..23ae534ee5 100644
--- a/src/local_deep_research/vector_stores/implementations/faiss_store.py
+++ b/src/local_deep_research/vector_stores/implementations/faiss_store.py
@@ -395,6 +395,7 @@ class FaissVectorStore(BaseVectorStore):
if k <= 0:
return []
with self._read_guard():
+ q = self._prepare(query_vector)
if self._index.ntotal == 0:
return []
# Clamp k to the number of stored vectors: faiss allocates k*4 bytes
@@ -403,7 +404,6 @@ class FaissVectorStore(BaseVectorStore):
# than exist only pads the result with -1 slots we skip anyway, so
# this never changes the returned hits.
k = min(k, self._index.ntotal)
- q = self._prepare(query_vector)
distances, ids = self._index.search(q, k)
results: List[Tuple[int, float]] = []
for dist, vid in zip(distances[0], ids[0]):
diff --git a/tests/research_library/services/test_library_rag_service_coverage.py b/tests/research_library/services/test_library_rag_service_coverage.py
index 69b8a6b922..e12dacc7f2 100644
--- a/tests/research_library/services/test_library_rag_service_coverage.py
+++ b/tests/research_library/services/test_library_rag_service_coverage.py
@@ -1604,31 +1604,59 @@ class TestPreflightDimensionMismatch:
# that second call a no-op. We assert it fired at least once with
# the right args rather than pin the exact count.
svc._reset_index_state_for_rebuild.assert_any_call("col-1", rag_index)
+ # The write path is the ONLY path that probes the model dimension.
+ svc.embedding_manager.embeddings.embed_query.assert_called_once_with(
+ "dimension_check"
+ )
# In-memory record reflects the new dimension too.
assert rag_index.embedding_dimension == 768
@patch(f"{_MOD}.get_user_db_session")
- def test_preflight_dimension_mismatch_read_path_raises_without_mutating_state(
- self, mock_session_ctx, tmp_path
+ @patch(f"{_MOD}.VectorIndex")
+ def test_search_skips_dimension_probe_on_read_path(
+ self, mock_vector_index, mock_session_ctx, tmp_path
):
+ # Performance: a read-only search() must NOT burn an embedding
+ # round-trip probing the model dimension. A wrong-dimension query
+ # is rejected downstream by the vector store's ``_prepare`` (see
+ # FaissVectorStore), so the read path stays fail-closed without
+ # the proactive probe. Only WRITE paths (reset_stale_state=True)
+ # probe so they can rebuild on drift.
svc = _make_service()
svc._get_index_path = MagicMock(return_value=tmp_path / "hash.faiss")
index_path, rag_index = self._make_present_index(
tmp_path, stored_dim=384
)
+ # The real _preflight_index_path still runs through search() ->
+ # _get_vector_index(reset_stale_state=False); only
+ # _get_or_create_rag_index (DB) and the VectorIndex facade are
+ # short-circuited, so this asserts ONLY the preflight probe behaviour.
+ svc._get_or_create_rag_index = MagicMock(return_value=rag_index)
svc.integrity_manager.verify_file.return_value = (True, None)
svc.embedding_manager = MagicMock()
+ # If preflight probed, this 768-vector would mismatch the stored
+ # 384 and raise on the read path (the old behaviour).
svc.embedding_manager.embeddings.embed_query.return_value = [0.1] * 768
+ # The patched facade stands in for the real VectorIndex: its search
+ # returns [] and never embeds (the real downstream query embedding
+ # is the facade's job, not preflight's), so any call to the backend
+ # embed_query mock below is attributable ONLY to the preflight probe.
+ mock_vector_index.return_value.search.return_value = []
+
svc._reset_index_state_for_rebuild = MagicMock()
- with pytest.raises(RuntimeError, match="dimension mismatch"):
- svc._preflight_index_path(
- "col-1", rag_index, reset_stale_state=False
- )
+ # search() leaves reset_stale_state at its default False -> read path.
+ result = svc.search("query", "col-1", 3)
- # A read must not destroy a healthy collection.
+ # The facade delegated the query embedding downstream; preflight did NOT.
+ assert result == []
+ mock_vector_index.return_value.search.assert_called_once_with(
+ "query", 3
+ )
+ svc.embedding_manager.embeddings.embed_query.assert_not_called()
+ # A read must not destroy a healthy collection or wipe DB state.
assert index_path.exists()
assert rag_index.embedding_dimension == 384
mock_session_ctx.assert_not_called()
diff --git a/tests/research_library/services/test_multi_model_switch_revert.py b/tests/research_library/services/test_multi_model_switch_revert.py
index 5bc74e412b..a1e07c8928 100644
--- a/tests/research_library/services/test_multi_model_switch_revert.py
+++ b/tests/research_library/services/test_multi_model_switch_revert.py
@@ -60,9 +60,14 @@ _RAG_MOD = "local_deep_research.research_library.services.library_rag_service"
class _FakeEmbeddings(Embeddings):
"""Deterministic, network-free embeddings distinguished by model name and
dimension. Counts ``embed_documents`` calls (a real "was this re-embedded?"
- signal, distinct from ``embed_query`` which the dimension-check pre-flight
- and search both legitimately call without indicating a re-embed of any
- document)."""
+ signal, distinct from ``embed_query``, which WRITE-path indexing's
+ dimension-check pre-flight calls, and which search also calls to embed
+ its own query -- neither indicates a re-embed of any document. Search's
+ OWN pre-flight probe is SKIPPED on this read path (see
+ ``LibraryRAGService.search``'s docstring): a wrong-dimension or
+ otherwise degenerate query is rejected by the vector store's
+ ``_prepare`` instead, without ever calling ``embed_query`` for a
+ probe)."""
def __init__(self, name: str, dim: int):
self.name = name
diff --git a/tests/research_library/services/test_reconcile_collection_index.py b/tests/research_library/services/test_reconcile_collection_index.py
index 5121855d47..7b8d990739 100644
--- a/tests/research_library/services/test_reconcile_collection_index.py
+++ b/tests/research_library/services/test_reconcile_collection_index.py
@@ -10,6 +10,13 @@ Pins the safety invariants added in PR #5235 (review comment 5085604502):
* ``RagDocumentStatus.indexed_at`` is preserved for documents that
already had a status row; only newly durable documents get the
current timestamp.
+
+Also pins a PR #5284 review follow-up: unlike every other test above (which
+stubs ``_get_vector_index`` wholesale), ``TestReconcileDimensionDrift`` below
+lets the REAL ``_get_vector_index`` / ``_preflight_index_path`` chain run, so
+it actually exercises the ``probe_dimension=True`` this call site passes --
+reconcile never embeds a query itself, so it has no ``_prepare`` of its own
+to catch an embedding-provider dimension drift for it.
"""
from datetime import datetime, UTC
@@ -324,3 +331,98 @@ class TestReconcilePartialDurabilityAndOrphans:
assert result["indexed_chunks"] == 1
assert result["live_vectors"] == 2
assert result["orphan_vectors"] == 1
+
+
+class TestReconcileDimensionDrift:
+ """R3 (PR #5284 review follow-up): ``reconcile_collection_index`` is a
+ SECOND ``reset_stale_state=False`` call site (besides ``search()``), but
+ unlike ``search()`` it never embeds a query -- it only calls
+ ``live_ids()`` -- so it gets none of the free fail-closed dimension
+ check ``FaissVectorStore._prepare`` gives a real search. Without
+ explicitly opting back in, an embedding-provider dimension drift (e.g.
+ repointing an OpenAI-compatible ``base_url`` from a local server to a
+ cloud one under the same model name -- the one drift PR #5284's gate
+ review found genuinely reachable) would go completely undetected here:
+ the stamped ``embedding_dimension`` still matches the stale on-disk
+ file, and a non-empty ``live_ids()`` means the refuse-to-shrink guard
+ below never fires either. ``_get_vector_index`` now passes
+ ``probe_dimension=True`` so ``_preflight_index_path`` runs the SAME
+ probe-and-rebuild-on-drift logic a WRITE path uses (see
+ ``TestPreflightDimensionMismatch`` in
+ ``test_library_rag_service_coverage.py`` for that logic's own direct
+ coverage, which this test's setup mirrors).
+
+ Unlike every other test in this module, this one does NOT stub
+ ``_get_vector_index`` -- doing so would bypass the very
+ ``probe_dimension`` plumbing under test. Only ``_get_or_create_rag_index``
+ and the ``VectorIndex`` facade construction are stubbed, exactly as
+ ``test_search_skips_dimension_probe_on_read_path`` does for the
+ ``search()`` read path.
+ """
+
+ def _make_present_index(self, tmp_path, stored_dim=384):
+ index_path = tmp_path / "hash.faiss"
+ index_path.write_bytes(b"faiss-bytes")
+ rag_index = MagicMock(
+ id=42,
+ index_hash="hash",
+ index_path=str(index_path),
+ embedding_dimension=stored_dim,
+ chunk_count=5,
+ total_documents=1,
+ )
+ return index_path, rag_index
+
+ @patch(f"{_MOD}.get_user_db_session")
+ @patch(f"{_MOD}.VectorIndex")
+ def test_reconcile_probes_dimension_and_reports_skip_on_drift(
+ self, mock_vector_index, mock_session_ctx, tmp_path
+ ):
+ svc = _make_service()
+ svc._get_index_path = MagicMock(return_value=tmp_path / "hash.faiss")
+ index_path, rag_index = self._make_present_index(
+ tmp_path, stored_dim=384
+ )
+ svc._get_or_create_rag_index = MagicMock(return_value=rag_index)
+ svc.integrity_manager.verify_file.return_value = (True, None)
+ svc.embedding_manager = MagicMock()
+ # The live embedding provider now returns 768-dim vectors -- drifted
+ # from the 384 stamped on the RAGIndex row / stale on-disk file.
+ svc.embedding_manager.embeddings.embed_query.return_value = [0.1] * 768
+
+ session = MagicMock()
+ mock_session_ctx.return_value.__enter__.return_value = session
+ db_row = MagicMock(embedding_dimension=384)
+ # Shared query mock: `.first()` serves `_preflight_index_path`'s own
+ # RAGIndex dimension update; `.all()` serves reconcile's own
+ # DocumentChunk rows query below -- a chunk row still on record for
+ # a document that was indexed under the OLD, pre-drift dimension.
+ q = session.query.return_value.filter_by.return_value
+ q.first.return_value = db_row
+ q.all.return_value = [(101, "doc-1")]
+
+ svc._reset_index_state_for_rebuild = MagicMock()
+ # After a drift-triggered rebuild, the facade's live_ids() comes
+ # back empty (a freshly (re)created index has nothing in it yet).
+ mock_vector_index.return_value.live_ids.return_value = []
+
+ result = svc.reconcile_collection_index("col-1")
+
+ # The probe fired and detected drift: the SAME rebuild machinery a
+ # WRITE path uses on a dimension mismatch (see
+ # test_preflight_dimension_mismatch_rebuilds_and_updates_dimension_on_write_path
+ # in test_library_rag_service_coverage.py). These are the
+ # falsifying assertions: revert the `probe_dimension=True` plumbing
+ # and every one of them fails (the probe never runs).
+ svc.embedding_manager.embeddings.embed_query.assert_called_once_with(
+ "dimension_check"
+ )
+ assert not index_path.exists()
+ assert db_row.embedding_dimension == 768
+ assert rag_index.embedding_dimension == 768
+ svc._reset_index_state_for_rebuild.assert_any_call("col-1", rag_index)
+ # Reconcile itself refuses to proceed once the rebuilt index comes
+ # back empty while chunk rows still exist for the collection --
+ # reported the same way a transient store fault is: skipped, not a
+ # silent mass-clear of every indexed flag.
+ assert result["reconciliation_skipped"] is True
diff --git a/tests/research_library/services/test_search_dimension_mismatch.py b/tests/research_library/services/test_search_dimension_mismatch.py
new file mode 100644
index 0000000000..6bdab5114e
--- /dev/null
+++ b/tests/research_library/services/test_search_dimension_mismatch.py
@@ -0,0 +1,274 @@
+"""Component coverage for the ``LibraryRAGService.search()`` dimension-mismatch
+translator (PR #5284 review follow-up).
+
+The translator converts ``FaissVectorStore._prepare``'s ``ValueError`` (raised
+when a query embedding's dimension differs from the index's, or when it is
+otherwise degenerate -- non-finite, zero-magnitude, or overflow-magnitude)
+into a service-level ``RuntimeError`` carrying collection context, preserving
+the legacy exception contract that pre-#5284 callers/logs depended on.
+
+The existing skip-path test mocks ``VectorIndex`` wholesale, so the real
+``search()`` translator branch was never exercised. This module:
+ * confirms the real ``FaissVectorStore._prepare`` raises a ``ValueError``
+ with the exact dimension-mismatch message recognized by the translator;
+ * drives the REAL ``LibraryRAGService.search()`` translator branch with a
+ realistic dimension-mismatch ``ValueError``, asserting it becomes a
+ ``RuntimeError`` with collection context + chained cause;
+ * pins that NON-dimension ``ValueError``s pass through unchanged;
+ * drives a REAL ``FaissVectorStore`` (not a stand-in) dimension mismatch
+ through the REAL translator end to end, so the translator's regex is
+ pinned against ``_prepare``'s ACTUAL wording rather than a copy of it
+ (a two-step drift -- changing ``_prepare``'s message and the store-level
+ test's literal together -- would still fail this one); and
+ * drives a REAL, EMPTY ``FaissVectorStore``'s zero-magnitude / non-finite
+ query rejection through that same real translator: ``_prepare`` now runs
+ BEFORE the ``ntotal == 0`` early return (see ``faiss_store.py``'s
+ ``search()``), so those degenerate-embedding rejections must become the
+ same shape of service-level ``RuntimeError`` as a dimension mismatch, not
+ a raw ``ValueError`` escaping to the caller.
+"""
+
+from __future__ import annotations
+
+import threading
+
+import numpy as np
+import pytest
+from langchain_core.embeddings import Embeddings
+
+from local_deep_research.database.models.library import EmbeddingProvider
+from local_deep_research.research_library.services.library_rag_service import (
+ LibraryRAGService,
+)
+from local_deep_research.vector_stores.facade import VectorIndex
+from local_deep_research.vector_stores.implementations.faiss_store import (
+ FaissVectorStore,
+)
+
+
+def _vecs(n: int, dim: int = 4, seed: int = 0) -> np.ndarray:
+ rng = np.random.default_rng(seed)
+ return rng.random((n, dim), dtype=np.float32)
+
+
+class _RaisingVectorIndex:
+ """Stand-in vector index whose ``search`` raises a given error.
+
+ Drives the REAL ``LibraryRAGService.search()`` translator branch with a
+ realistic dimension-mismatch ``ValueError`` (the same shape the real
+ ``FaissVectorStore._prepare`` produces), so the translator's
+ try/except/raise executes against the real method rather than being mocked
+ away. Only the vector-index leaf is faked; the service method is real.
+ """
+
+ def __init__(self, error: BaseException) -> None:
+ self._error = error
+
+ def search(self, query: object, top_k: int) -> list: # noqa: ANN001
+ raise self._error
+
+
+def _bare_service() -> LibraryRAGService:
+ """A ``LibraryRAGService`` with ``__init__`` bypassed (only search() runs)."""
+ return object.__new__(LibraryRAGService)
+
+
+# --- the real FaissVectorStore really raises ValueError("...dimension...") ----
+
+
+def test_faiss_prepare_raises_dimension_valueerror(tmp_path) -> None:
+ """Pin the exact store message recognized by the service translator."""
+ store = FaissVectorStore.create(
+ dimension=4,
+ index_type="flat",
+ metric="cosine",
+ normalize=True,
+ path=tmp_path / "coll.faiss",
+ lock=threading.Lock(),
+ integrity_record=lambda _p: None,
+ integrity_verify=lambda _p: (True, None),
+ )
+ store.add([1], _vecs(1, dim=4))
+
+ with pytest.raises(
+ ValueError, match=r"^vector dimension 8 != index dimension 4$"
+ ):
+ store.search(_vecs(1, dim=8)[0], 1)
+
+
+# --- the real LibraryRAGService.search() translator --------------------------
+
+
+def test_search_translates_dimension_valueerror_to_runtimeerror(
+ monkeypatch,
+) -> None:
+ """Drive the REAL ``search()`` method: a dimension-mismatch ``ValueError``
+ from the vector index is translated to a ``RuntimeError`` carrying the
+ collection context."""
+ service = _bare_service()
+ monkeypatch.setattr(
+ service,
+ "_get_vector_index",
+ lambda _cid, _name: _RaisingVectorIndex(
+ ValueError("vector dimension 8 != index dimension 4")
+ ),
+ )
+
+ with pytest.raises(RuntimeError) as exc_info:
+ service.search("any query", "coll-123", 5)
+
+ msg = str(exc_info.value).lower()
+ assert "dimension mismatch" in msg
+ assert "coll-123" in str(exc_info.value) # collection context preserved
+ # The underlying ValueError is chained, not discarded.
+ assert isinstance(exc_info.value.__cause__, ValueError)
+
+
+ "message",
+ [
+ "zero-magnitude query",
+ "unsupported dimensions parameter",
+ "provider refused vector dimension 8 != index dimension 4",
+ ],
+)
+def test_search_passes_through_non_dimension_valueerror(
+ monkeypatch, message
+) -> None:
+ """Non-dimension ``ValueError``s pass through unchanged. Each parametrized
+ message is deliberately a NEAR-miss of a real ``_prepare`` message
+ (different wording, an added prefix, etc.) -- the translator matches
+ exact formats only, both for the dimension regex and for the fixed-text
+ degenerate-embedding messages (see the real-store tests below), so a
+ provider ``ValueError`` that merely resembles one of those keeps passing
+ through unchanged rather than being rewired."""
+ service = _bare_service()
+ monkeypatch.setattr(
+ service,
+ "_get_vector_index",
+ lambda _cid, _name: _RaisingVectorIndex(ValueError(message)),
+ )
+
+ with pytest.raises(ValueError) as exc_info:
+ service.search("any query", "coll-123", 5)
+
+ assert str(exc_info.value) == message
+
+
+# --- real end-to-end: a genuine FaissVectorStore driving the real search() --
+
+
+class _FixedVectorEmbeddings(Embeddings):
+ """Returns the SAME fixed vector for every query, regardless of the query
+ text. Lets a test pin exactly which vector reaches the real
+ ``FaissVectorStore._prepare`` without depending on any real embedding
+ model (no network, no model load -- see ``_FakeEmbeddings`` in
+ ``tests/vector_stores/test_facade.py`` for the same pattern)."""
+
+ def __init__(self, vector: np.ndarray) -> None:
+ self._vector = vector
+
+ def embed_documents(self, texts): # pragma: no cover - unused by search()
+ return [self._vector.tolist() for _ in texts]
+
+ def embed_query(self, text):
+ return self._vector.tolist()
+
+
+def _make_real_vector_index(
+ tmp_path, *, store_dimension: int, query_vector: np.ndarray
+) -> VectorIndex:
+ """A REAL ``VectorIndex`` wired to a REAL, freshly-created (empty)
+ ``FaissVectorStore`` on disk under ``tmp_path``. Only the embeddings
+ backend is faked (fixed output); ``_prepare`` itself is never mocked, so
+ whatever the real store does with ``query_vector`` is what ``search()``
+ really sees.
+ """
+ return VectorIndex(
+ username="testuser",
+ db_password="pw", # gitleaks:allow
+ embeddings=_FixedVectorEmbeddings(query_vector),
+ embedding_model="fake-model",
+ embedding_model_type=EmbeddingProvider.SENTENCE_TRANSFORMERS,
+ collection_name="collection_coll-123",
+ dimension=store_dimension,
+ path=tmp_path / "coll.faiss",
+ lock=threading.Lock(),
+ integrity_record=lambda _p: None,
+ integrity_verify=lambda _p: (True, None),
+ index_type="flat",
+ metric="cosine",
+ normalize=True,
+ )
+
+
+def test_search_real_store_dimension_mismatch_translates_end_to_end(
+ monkeypatch, tmp_path
+) -> None:
+ """R5: no ``_RaisingVectorIndex`` stand-in, no mocked ``_prepare`` -- a
+ REAL ``FaissVectorStore`` (dimension 4) raises its real
+ dimension-mismatch ``ValueError`` for a real dimension-8 query, and the
+ REAL ``LibraryRAGService.search()`` translator turns it into a
+ ``RuntimeError``. This pins the translator's regex against ``_prepare``'s
+ ACTUAL wording end to end, unlike
+ ``test_search_translates_dimension_valueerror_to_runtimeerror`` above
+ (which only drives the translator against a fake vector index whose
+ error text is hand-written, not produced by a real store)."""
+ service = _bare_service()
+ vindex = _make_real_vector_index(
+ tmp_path, store_dimension=4, query_vector=_vecs(1, dim=8)[0]
+ )
+ monkeypatch.setattr(
+ service, "_get_vector_index", lambda _cid, _name: vindex
+ )
+
+ with pytest.raises(RuntimeError) as exc_info:
+ service.search("any query", "coll-123", 5)
+
+ msg = str(exc_info.value)
+ assert "dimension mismatch" in msg.lower()
+ assert "coll-123" in msg
+ cause = exc_info.value.__cause__
+ assert isinstance(cause, ValueError)
+ assert str(cause) == "vector dimension 8 != index dimension 4"
+
+
+ "make_query",
+ [
+ pytest.param(lambda: np.zeros(4, dtype="float32"), id="zero_magnitude"),
+ pytest.param(
+ lambda: np.full(4, np.nan, dtype="float32"), id="non_finite"
+ ),
+ ],
+)
+def test_search_real_empty_store_degenerate_query_translates_end_to_end(
+ monkeypatch, tmp_path, make_query
+) -> None:
+ """R2: on an EMPTY store, ``_prepare`` runs BEFORE the ``ntotal == 0``
+ early return (see ``faiss_store.py``'s ``search()``), so a
+ zero-magnitude or non-finite query is rejected instead of silently
+ returning ``[]`` for a never-indexed collection -- and the real
+ ``search()`` translator turns that ``ValueError`` into the same shape of
+ service-level ``RuntimeError`` as a dimension mismatch, not a raw
+ exception escaping to the caller. Reverting the translator's widening to
+ cover these degenerate-embedding messages (as opposed to only the
+ dimension regex) fails this test: the pre-widening translator would let
+ this ``ValueError`` propagate raw instead of becoming a
+ ``RuntimeError``."""
+ service = _bare_service()
+ vindex = _make_real_vector_index(
+ tmp_path, store_dimension=4, query_vector=make_query()
+ )
+ assert vindex._store.count() == 0 # genuinely empty/never-indexed
+ monkeypatch.setattr(
+ service, "_get_vector_index", lambda _cid, _name: vindex
+ )
+
+ with pytest.raises(RuntimeError) as exc_info:
+ service.search("any query", "coll-123", 5)
+
+ msg = str(exc_info.value)
+ assert "coll-123" in msg
+ assert "degenerate" in msg.lower()
+ assert isinstance(exc_info.value.__cause__, ValueError)
diff --git a/tests/vector_stores/test_faiss_store.py b/tests/vector_stores/test_faiss_store.py
index 8fd3f4ff50..f375e76e7b 100644
--- a/tests/vector_stores/test_faiss_store.py
+++ b/tests/vector_stores/test_faiss_store.py
@@ -147,6 +147,32 @@ class TestSearchOrdering:
store = _make_store(tmp_path)
assert store.search(_vecs(1)[0], 5) == []
+ def test_search_empty_store_rejects_wrong_dimension_query(self, tmp_path):
+ store = _make_store(tmp_path, dimension=4)
+ query = _vecs(1, dim=8)[0]
+
+ with pytest.raises(ValueError):
+ store.search(query, 1)
+
+ def test_search_populated_store_rejects_wrong_dimension_query(
+ self, tmp_path
+ ):
+ # NOTE: this does NOT discriminate the `_prepare`-before-`ntotal==0`
+ # reorder in `search()` — a POPULATED index never takes the early
+ # `return []` under either ordering, so this still passes with that
+ # reorder fully reverted. The real pin for the reorder is the
+ # EMPTY-store sibling above
+ # (test_search_empty_store_rejects_wrong_dimension_query): before
+ # the reorder, an empty store returned `[]` for a wrong-dimension
+ # query instead of raising. Keep both — don't delete the empty-store
+ # test as a "duplicate" of this one.
+ store = _make_store(tmp_path, dimension=4)
+ store.add([1], _vecs(1, dim=4))
+ query = _vecs(1, dim=8)[0]
+
+ with pytest.raises(ValueError):
+ store.search(query, 1)
+
def test_search_fewer_hits_than_k_drops_empty_slots(self, tmp_path):
"""faiss returns -1 for empty slots when fewer than k neighbors
exist; those must be filtered out, not surfaced as id -1."""