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.

fix(embeddings): admit existing local-path models under require_local (#4924)

LearningCircuiteed99fa51c56
diff --git a/changelog.d/4924.bugfix.md b/changelog.d/4924.bugfix.md
new file mode 100644
index 0000000000..fc8364bd7b
--- /dev/null
+++ b/changelog.d/4924.bugfix.md
@@ -0,0 +1 @@
+Under `embeddings.require_local=True` (or any `PRIVATE_ONLY` egress scope), a collection search whose embedding model is configured as an existing **local directory path** was wrongly refused with `policy_denied: embeddings_model_not_cached`. The `require_local` pre-flight probed the path as a HuggingFace `repo_id`, which raised a validation error that was swallowed and treated as a cache miss — even though the SentenceTransformer loader resolves such a path locally and never contacts the hub. The pre-flight now mirrors the loader's `os.path.exists` guard and admits an existing local path (blank/degenerate names still fail closed), so a local model directory is no longer false-denied.
diff --git a/src/local_deep_research/embeddings/providers/implementations/sentence_transformers.py b/src/local_deep_research/embeddings/providers/implementations/sentence_transformers.py
index c4938f8759..bc335edefe 100644
--- a/src/local_deep_research/embeddings/providers/implementations/sentence_transformers.py
+++ b/src/local_deep_research/embeddings/providers/implementations/sentence_transformers.py
@@ -1,5 +1,6 @@
"""Sentence Transformers embedding provider."""
+from pathlib import Path
from typing import Any, Dict, List, Optional
from langchain_core.embeddings import Embeddings
@@ -149,8 +150,14 @@ class SentenceTransformersProvider(BaseEmbeddingProvider):
target=model,
)
# Force the inner ``transformers``/``sentence_transformers``
- # call to use cached files only — defence in depth in case
- # the cache check above misses an alternative cache path.
+ # call to use cached files only. Defence in depth for the
+ # HF-cache branch — but LOAD-BEARING for the local-path admit
+ # in ``_is_model_cached_locally``: that admit only checks the
+ # path exists, doing zero content validation, so an existing
+ # model dir whose config references an UNCACHED remote base
+ # would otherwise fetch it here. Keep this set for every
+ # require_local admit; do not relax it on the assumption that
+ # the pre-flight already proved the model fully local.
model_kwargs["local_files_only"] = True
return SentenceTransformerEmbeddings(
@@ -172,6 +179,22 @@ class SentenceTransformersProvider(BaseEmbeddingProvider):
or misses, so no special-casing is needed.
"""
try:
+ # A model configured as an existing local path is already on
+ # disk: ``SentenceTransformer.__init__`` takes its
+ # ``os.path.exists`` branch and never touches the network, so
+ # it's admissible under require_local. Mirror that guard first
+ # — before treating the name as an HF repo_id, since a path
+ # with "/" would otherwise be probed as a repo_id and rejected
+ # as malformed (a false ``embeddings_model_not_cached``).
+ #
+ # The ``model_name and`` guard is load-bearing: ``Path("")``
+ # normalises to ``.`` (the cwd, which exists), so a blank
+ # config would wrongly admit — whereas the loader's
+ # ``os.path.exists("")`` returns False. The truthiness check
+ # restores fail-closed parity for the degenerate empty name.
+ if model_name and Path(model_name).exists():
+ return True
+
from huggingface_hub import try_to_load_from_cache
# Probe both the bare and the namespaced cache keys when the
diff --git a/tests/security/test_egress_policy.py b/tests/security/test_egress_policy.py
index ff478771ff..9b11e723a5 100644
--- a/tests/security/test_egress_policy.py
+++ b/tests/security/test_egress_policy.py
@@ -2063,6 +2063,54 @@ def test_sbert_cache_check_treats_non_string_returns_as_misses(miss_value):
)
+def test_sbert_cache_check_admits_existing_local_path(tmp_path):
+ """A model configured as an existing local directory is already on
+ disk — the loader takes its ``os.path.exists`` branch and never hits
+ the network, so it must be admitted under require_local without an
+ HF cache probe. Before this guard the path was probed as an HF
+ repo_id, raised HFValidationError, was swallowed, and false-denied
+ with ``embeddings_model_not_cached``. Differential: returns False on
+ the pre-guard code.
+ """
+ from local_deep_research.embeddings.providers.implementations.sentence_transformers import (
+ SentenceTransformersProvider,
+ )
+
+ # tmp_path is an existing directory. The admit checks only that the
+ # path exists (no config.json / model-structure validation), so a
+ # bare existing dir is sufficient — mirroring the loader's
+ # os.path.exists guard, which likewise does not inspect contents.
+ with patch("huggingface_hub.try_to_load_from_cache") as mock_cache:
+ assert (
+ SentenceTransformersProvider._is_model_cached_locally(str(tmp_path))
+ is True
+ )
+ # Local-path admission short-circuits before any HF cache probe.
+ mock_cache.assert_not_called()
+
+
+def test_sbert_cache_check_blank_name_not_treated_as_existing_path():
+ """Regression guard for the ``Path("")`` quirk: an empty model_name
+ normalises to ``.`` (the cwd, which exists), so a naive
+ ``Path(model_name).exists()`` would wrongly admit a blank config.
+ The ``model_name and`` truthiness guard keeps it fail-closed, in
+ parity with the loader's ``os.path.exists("") is False``.
+ """
+ from local_deep_research.embeddings.providers.implementations.sentence_transformers import (
+ SentenceTransformersProvider,
+ )
+
+ assert SentenceTransformersProvider._is_model_cached_locally("") is False
+ # Whitespace is truthy, so unlike "" it DOES reach Path.exists() — it
+ # must still miss (no such path) and fall through to fail-closed,
+ # rather than being admitted as a local path.
+ with patch("huggingface_hub.try_to_load_from_cache", return_value=None):
+ assert (
+ SentenceTransformersProvider._is_model_cached_locally(" ")
+ is False
+ )
+
+
def test_sentence_transformers_model_hub_organization_pin():
"""Pin the private ``__MODEL_HUB_ORGANIZATION__`` constant that
``_is_model_cached_locally`` uses to build the namespaced cache key