~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.
Python academiaanthropicarxivbravedeep-researchencryptionhome-automationhomeserverlocallocal-deep-researchlocal-llmmistralollamaopenaipubmedresearchresearch-toolretrieval-augmented-generationsearxngself-hosted
perf(rag): skip dimension probe on search paths (#5284)
LearningCircuit4720e696fbfc
diff --git a/changelog.d/5284.misc.md b/changelog.d/5284.misc.mdnew file mode 100644index 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.pyindex 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 threadingimport timeimport json+import refrom contextlib import contextmanagerfrom dataclasses import dataclassfrom 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 currentvalues — 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 staysthe 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 = Trueelif 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_dimensionif 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 ownexistence 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_indexindex_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 hasindexed 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+ raisedef 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.iddiff --git a/src/local_deep_research/vector_stores/implementations/faiss_store.py b/src/local_deep_research/vector_stores/implementations/faiss_store.pyindex 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.pyindex 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 == 384mock_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.pyindex 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 anddimension. 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 = namediff --git a/tests/research_library/services/test_reconcile_collection_index.py b/tests/research_library/services/test_reconcile_collection_index.pyindex 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 thatalready had a status row; only newly durable documents get thecurrent 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"] == 1assert result["live_vectors"] == 2assert 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 Truediff --git a/tests/research_library/services/test_search_dimension_mismatch.py b/tests/research_library/services/test_search_dimension_mismatch.pynew file mode 100644index 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.pyindex 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 neighborsexist; those must be filtered out, not surfaced as id -1."""