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(search_engines): add Elasticsearch availability probe and pre-probe eligibility filtering (#5270) (#5271)

S0fa494fc0e72
diff --git a/src/local_deep_research/advanced_search_system/filters/journal_reputation_filter.py b/src/local_deep_research/advanced_search_system/filters/journal_reputation_filter.py
index 805e923675..d035db9167 100644
--- a/src/local_deep_research/advanced_search_system/filters/journal_reputation_filter.py
+++ b/src/local_deep_research/advanced_search_system/filters/journal_reputation_filter.py
@@ -279,7 +279,7 @@ class JournalReputationFilter(BaseFilter):
"searxng", llm=self.model, settings_snapshot=settings_snapshot
)
self.__searxng_available = self.__engine is not None and getattr(
- self.__engine, "is_available", False
+ self.__engine, "_is_available", False
)
if not self.__searxng_available:
logger.info(
diff --git a/src/local_deep_research/advanced_search_system/strategies/langgraph_agent_strategy.py b/src/local_deep_research/advanced_search_system/strategies/langgraph_agent_strategy.py
index af246dbb92..aaadf8cdc1 100644
--- a/src/local_deep_research/advanced_search_system/strategies/langgraph_agent_strategy.py
+++ b/src/local_deep_research/advanced_search_system/strategies/langgraph_agent_strategy.py
@@ -402,6 +402,8 @@ def _load_specialized_engine_tools(
# — this discovery change restores symmetry with #4453.
eligible = list_eligible_engine_configs(
settings_snapshot=settings_snapshot,
+ egress_context=egress_context,
+ check_agent_enabled=True,
)
for name, config in eligible.items():
if name == skip_engine:
@@ -410,6 +412,7 @@ def _load_specialized_engine_tools(
# Per-engine usability switch (independent of egress). Collection
# configs carry their DB flag; built-in engines receive the
# flattened search.engine.web.<name>.agent_enabled setting.
+ # Note: Re-checked here to log debug info for specialized tools.
# Missing flags default to available for backward compatibility.
# The primary engine was skipped above and remains reachable
# through the caller's generic web_search tool.
@@ -422,7 +425,9 @@ def _load_specialized_engine_tools(
continue
# Under STRICT, register no specialized engines at all — the
- # agent gets only its primary web_search tool.
+ # agent gets only its primary web_search tool. (Note: STRICT-scope
+ # blanket-skip is intentionally enforced here as list_eligible_engine_configs
+ # does not blanket-enforce STRICT).
if (
egress_context is not None
and egress_context.scope == EgressScope.STRICT
@@ -430,7 +435,9 @@ def _load_specialized_engine_tools(
continue
# Under PUBLIC_ONLY / PRIVATE_ONLY, ask the PDP whether this
- # engine fits the scope. Retrievers route to evaluate_retriever
+ # engine fits the scope. Re-evaluating here produces policy_audit
+ # log entries for specialized tools filtered by egress policy.
+ # Retrievers route to evaluate_retriever
# (engine-PDP returns engine_unknown for them); plain engines
# route to evaluate_engine.
if egress_context is not None:
diff --git a/src/local_deep_research/web_search_engines/engines/search_engine_elasticsearch.py b/src/local_deep_research/web_search_engines/engines/search_engine_elasticsearch.py
index f39b863ac2..3f5c993531 100644
--- a/src/local_deep_research/web_search_engines/engines/search_engine_elasticsearch.py
+++ b/src/local_deep_research/web_search_engines/engines/search_engine_elasticsearch.py
@@ -1,4 +1,6 @@
+import json
from ...security.secure_logging import logger
+import time as _time
from typing import Any, Dict, List, Optional
from elasticsearch import Elasticsearch
@@ -73,6 +75,158 @@ class ElasticsearchSearchEngine(BaseSearchEngine):
)
return True
+ # TTL cache for ``is_available`` probes. Keyed by JSON string representation of hosts so
+ # two instances pointing at different clusters don't poison each other (and dict hosts don't raise TypeError).
+ # The cache lives on the class so test patches that replace the class don't fight a stale module-level dict.
+ # A negative result (connection refused / timeout) is cached for the same TTL — we don't
+ # want a misconfigured engine to cost a TCP round-trip on every research run.
+ _availability_cache: Dict[str, tuple[float, bool]] = {}
+ _AVAILABILITY_TTL_SECONDS = 60.0
+
+ @classmethod
+ def clear_availability_cache(cls) -> None:
+ """Clear the cached availability probe results."""
+ cls._availability_cache.clear()
+
+ @classmethod
+ def is_available(
+ cls, settings_snapshot: Optional[Dict[str, Any]] = None
+ ) -> bool:
+ """Probe the configured Elasticsearch host(s) with a cheap TCP connect.
+
+ ``ElasticsearchSearchEngine.__init__`` calls ``self.client.info()``
+ which raises ``ConnectionError`` when the cluster is unreachable.
+ Without this probe the factory logs ``Failed to create search
+ engine 'elasticsearch' (ConnectionError)`` on every tool call, and
+ worse the langgraph agent still advertises the engine as a tool in
+ its per-step "selecting next action from …" heartbeat.
+
+ We do a bare TCP connect (not the full ES handshake) so the probe
+ stays cheap enough to call from ``list_eligible_engine_configs``.
+ Negative results are cached for ``_AVAILABILITY_TTL_SECONDS`` so a
+ single down cluster doesn't cost a round-trip per research run.
+
+ Returns True (fail-open) for ``cloud_id`` configurations — those
+ target Elastic Cloud and a TCP probe isn't meaningful. They'll
+ surface their own error in ``__init__`` if misconfigured.
+ """
+ from ...config.thread_settings import get_setting_from_snapshot
+
+ try:
+ snapshot = settings_snapshot or {}
+
+ # cloud_id configs don't have a host we can TCP-probe. Trust them;
+ # __init__ surfaces a useful error if the cluster is unreachable.
+ cloud_id = get_setting_from_snapshot(
+ "search.engine.web.elasticsearch.default_params.cloud_id",
+ "",
+ settings_snapshot=snapshot,
+ )
+ if cloud_id:
+ return True
+
+ hosts_setting = get_setting_from_snapshot(
+ "search.engine.web.elasticsearch.default_params.hosts",
+ ["http://localhost:9200"],
+ settings_snapshot=snapshot,
+ )
+ # The setting can arrive as a JSON string (ui_element=json) or a
+ # real list — mirror the normalization __init__ does.
+ hosts = cls._ensure_list(
+ hosts_setting, default=["http://localhost:9200"]
+ )
+ try:
+ cache_key = json.dumps(hosts, sort_keys=True, default=str)
+ except Exception:
+ cache_key = str(hosts)
+
+ now = _time.monotonic()
+ cached = cls._availability_cache.get(cache_key)
+ if cached is not None:
+ ts, available = cached
+ if now - ts < cls._AVAILABILITY_TTL_SECONDS:
+ return available
+
+ available = cls._probe_hosts_available(hosts)
+ cls._availability_cache[cache_key] = (now, available)
+ if not available:
+ logger.info(
+ "Elasticsearch availability probe failed; excluding from "
+ "agent tool list. Will re-probe in {:.0f}s.",
+ cls._AVAILABILITY_TTL_SECONDS,
+ )
+ return available
+ except Exception as exc:
+ logger.debug(
+ "Elasticsearch is_available probe raised exception ({}) — failing open",
+ type(exc).__name__,
+ )
+ return True
+
+ @staticmethod
+ def _probe_hosts_available(hosts: List[Any]) -> bool:
+ """TCP-connect to the first reachable host in ``hosts``.
+
+ Any single host responding makes the engine available — matches the
+ Elasticsearch client behavior of treating the list as failover.
+ Cheap (no HTTP) and short-timeout (1s per host, capped at 2.0s aggregate
+ budget across all hosts) so the worst case is strictly bounded.
+ Each host is validated against SSRF rules before connecting.
+ """
+ import socket
+ from urllib.parse import urlparse
+ from ...security.ssrf_validator import validate_url
+
+ start_time = _time.monotonic()
+ total_budget = 2.0 # Cap aggregate probe duration across all hosts
+
+ for host in hosts:
+ elapsed = _time.monotonic() - start_time
+ remaining = total_budget - elapsed
+ if remaining <= 0:
+ break
+
+ if isinstance(host, dict):
+ hostname = host.get("host") or host.get("hostname")
+ if not hostname:
+ continue
+ scheme = host.get("scheme", "http")
+ port = host.get("port")
+ if port is None:
+ port = 443 if scheme == "https" else 9200
+ elif isinstance(host, str):
+ url_str = host if "://" in host else f"http://{host}"
+ try:
+ parsed = urlparse(url_str)
+ hostname = parsed.hostname or host
+ scheme = parsed.scheme or "http"
+ port = parsed.port
+ if port is None:
+ port = 443 if scheme == "https" else 9200
+ except ValueError:
+ continue
+ else:
+ continue
+
+ probe_url = f"{scheme}://{hostname}:{port}"
+ if not validate_url(
+ probe_url, allow_localhost=True, allow_private_ips=True
+ ):
+ logger.warning(
+ "Elasticsearch host failed SSRF validation: {}", probe_url
+ )
+ continue
+
+ timeout = min(remaining, 1.0)
+ try:
+ with socket.create_connection(
+ (hostname, port), timeout=timeout
+ ):
+ return True
+ except (OSError, socket.timeout, ValueError):
+ continue
+ return False
+
def __init__(
self,
hosts: Optional[List[str]] = None,
diff --git a/src/local_deep_research/web_search_engines/engines/search_engine_searxng.py b/src/local_deep_research/web_search_engines/engines/search_engine_searxng.py
index 515d495472..a4d5f21f2f 100644
--- a/src/local_deep_research/web_search_engines/engines/search_engine_searxng.py
+++ b/src/local_deep_research/web_search_engines/engines/search_engine_searxng.py
@@ -153,14 +153,14 @@ class SearXNGSearchEngine(BaseSearchEngine):
)
if response.status_code == 200:
logger.info("SearXNG instance is accessible.")
- self.is_available = True
+ self._is_available = True
else:
- self.is_available = False
+ self._is_available = False
logger.error(
f"Failed to access SearXNG instance at {redact_url_for_log(self.instance_url)}. Status code: {response.status_code}"
)
except (requests.RequestException, ValueError) as e:
- self.is_available = False
+ self._is_available = False
safe_msg = self._scrub_error(e)
logger.exception(
f"Error while trying to access SearXNG instance at {redact_url_for_log(self.instance_url)} ({type(e).__name__}): {safe_msg}"
@@ -169,7 +169,7 @@ class SearXNGSearchEngine(BaseSearchEngine):
# Add debug logging for all parameters
logger.info(
f"SearXNG init params: max_results={max_results}, language={language}, "
- f"max_filtered_results={max_filtered_results}, is_available={self.is_available}"
+ f"max_filtered_results={max_filtered_results}, is_available={self._is_available}"
)
self.max_results = max_results
@@ -203,7 +203,7 @@ class SearXNGSearchEngine(BaseSearchEngine):
self.delay_between_requests = float(delay_between_requests)
- if self.is_available:
+ if self._is_available:
self.search_url = f"{self.instance_url}/search"
logger.info(
f"SearXNG engine initialized with instance: {redact_url_for_log(self.instance_url)}"
@@ -245,7 +245,7 @@ class SearXNGSearchEngine(BaseSearchEngine):
Returns:
List of search results from SearXNG
"""
- if not self.is_available:
+ if not self._is_available:
logger.error(
"SearXNG engine is disabled (no instance URL provided) - cannot run search"
)
@@ -534,7 +534,7 @@ class SearXNGSearchEngine(BaseSearchEngine):
Returns:
List of preview dictionaries
"""
- if not self.is_available:
+ if not self._is_available:
logger.warning(
"SearXNG engine is disabled (no instance URL provided)"
)
@@ -579,7 +579,7 @@ class SearXNGSearchEngine(BaseSearchEngine):
Returns:
List of result dictionaries with full content
"""
- if not self.is_available:
+ if not self._is_available:
return relevant_items
if not hasattr(self, "full_search"):
@@ -614,7 +614,7 @@ class SearXNGSearchEngine(BaseSearchEngine):
Returns:
List of search result dictionaries
"""
- if not self.is_available:
+ if not self._is_available:
return []
original_max_results = self.max_results
@@ -701,7 +701,7 @@ https://searxng.github.io/searxng/admin/installation.html
"""
Override BaseSearchEngine run method to add SearXNG-specific error handling.
"""
- if not self.is_available:
+ if not self._is_available:
logger.error(
"SearXNG run method called but engine is not available (missing instance URL)"
)
diff --git a/src/local_deep_research/web_search_engines/search_engine_base.py b/src/local_deep_research/web_search_engines/search_engine_base.py
index 68625dc112..63e3fff8c6 100644
--- a/src/local_deep_research/web_search_engines/search_engine_base.py
+++ b/src/local_deep_research/web_search_engines/search_engine_base.py
@@ -274,6 +274,29 @@ class BaseSearchEngine(ABC):
except Exception as e:
return False, None, f"Could not load engine class for {name}: {e}"
+ @classmethod
+ def is_available(
+ cls, settings_snapshot: Optional[Dict[str, Any]] = None
+ ) -> bool:
+ """Runtime availability probe used by ``list_eligible_engine_configs``.
+
+ Subclasses whose ``__init__`` performs a network probe that can
+ hard-fail (e.g. Elasticsearch's ``client.info()`` raises
+ ``ConnectionError`` when the cluster is unreachable) should override
+ this to fail closed: returning ``False`` causes the engine to be
+ omitted from the agent's tool surface AND the auto-search pool, so
+ the heartbeat never advertises a broken tool and the factory never
+ logs ``Failed to create search engine '<name>' (ConnectionError)``
+ per step.
+
+ Default is ``True`` — engines that don't probe at init stay
+ eligible. This is the opposite default of ``BaseLLMProvider`` because
+ the vast majority of search engines here are pure REST clients with
+ lazy connection errors; changing the default would force every
+ subclass to opt in to ``True`` for no benefit.
+ """
+ return True
+
def __init__(
self,
llm: Optional[BaseLLM] = None,
diff --git a/src/local_deep_research/web_search_engines/search_engine_factory.py b/src/local_deep_research/web_search_engines/search_engine_factory.py
index a8fcae4402..d988ff81e0 100644
--- a/src/local_deep_research/web_search_engines/search_engine_factory.py
+++ b/src/local_deep_research/web_search_engines/search_engine_factory.py
@@ -738,8 +738,21 @@ def get_search(
else:
logger.error("Engine does NOT have 'run' method!")
- # For SearxNG, check availability flag
- if hasattr(engine, "is_available"):
- logger.info(f"Engine availability flag: {engine.is_available}")
+ # Check engine availability flag / method
+ avail = None
+ if getattr(engine, "_is_available", None) is not None:
+ avail = getattr(engine, "_is_available")
+ elif hasattr(engine, "is_available"):
+ if callable(engine.is_available):
+ try:
+ avail = engine.is_available(
+ settings_snapshot=settings_snapshot
+ )
+ except TypeError:
+ avail = engine.is_available()
+ else:
+ avail = engine.is_available
+ if avail is not None:
+ logger.info(f"Engine availability flag: {avail}")
return engine
diff --git a/src/local_deep_research/web_search_engines/search_engines_config.py b/src/local_deep_research/web_search_engines/search_engines_config.py
index 7cf2dc7bf8..3dc2f61b15 100644
--- a/src/local_deep_research/web_search_engines/search_engines_config.py
+++ b/src/local_deep_research/web_search_engines/search_engines_config.py
@@ -276,6 +276,9 @@ def list_eligible_engine_configs(
settings_snapshot: Optional[Dict[str, Any]] = None,
*,
use_api_key_services: bool = True,
+ egress_context: Optional[Any] = None,
+ check_agent_enabled: bool = False,
+ check_auto_search: bool = False,
) -> Dict[str, Any]:
"""Return every engine from ``search_config`` that can be instantiated.
@@ -287,19 +290,34 @@ def list_eligible_engine_configs(
credential check; everything else (retrievers, the built-in ``library``
engine, dynamic ``collection_*`` entries) flows through.
- The name keys the dict are the canonical engine names from
- ``search_config`` (e.g. ``semantic_scholar``, ``ddg``) — matching the
+ The name keys in the returned dict are the canonical engine names from
+ ``search_config`` (e.g. ``searxng``, ``elasticsearch``) — matching the
registry in ``engine_registry.py`` 1:1, so callers can compare against
``search.tool`` directly.
+ Engines whose ``is_available(settings_snapshot)`` returns ``False`` are
+ excluded — this catches the case where the engine is configured but its
+ backing service is unreachable (e.g. Elasticsearch with no running
+ cluster on ``localhost:9200``). Without this filter the agent still
+ SEES the broken engine as a tool in its heartbeat and the factory logs
+ ``Failed to create search engine '<name>' (ConnectionError)`` per step.
+ Subclasses of ``BaseSearchEngine`` override ``is_available`` to opt in;
+ the default is True so existing engines are unaffected.
+
+ Filters for disabled state (``agent_enabled`` / ``use_in_auto_search``) and
+ egress policy are evaluated BEFORE calling ``is_available`` so unreachable or
+ disabled engines do not trigger unnecessary network probes.
+
Args:
settings_snapshot: Thread-safe settings snapshot.
use_api_key_services: When False, engines that require an API key
are excluded even when the key is present.
+ egress_context: Optional EgressContext to evaluate policy before probing.
+ check_agent_enabled: When True, excludes engines disabled for agent.
+ check_auto_search: When True, excludes engines disabled for auto-search.
Returns:
- Dict of engine_name → config for engines that passed the
- credential check.
+ Dict of engine_name → config for engines that passed all checks.
"""
if not settings_snapshot:
logger.warning(
@@ -310,6 +328,12 @@ def list_eligible_engine_configs(
all_engines = search_config(settings_snapshot=settings_snapshot)
+ if egress_context is not None:
+ from ..security.egress.policy import (
+ evaluate_engine,
+ evaluate_retriever,
+ )
+
eligible: Dict[str, Any] = {}
for name, config in all_engines.items():
requires_key = config.get("requires_api_key", False)
@@ -324,11 +348,130 @@ def list_eligible_engine_configs(
)
continue
+ # Optional auto-search flag check prior to probe
+ if check_auto_search:
+ use_in_auto = config.get("use_in_auto_search")
+ if use_in_auto is None:
+ auto_search_key = f"search.engine.web.{name}.use_in_auto_search"
+ use_in_auto = get_setting_from_snapshot(
+ auto_search_key, False, settings_snapshot=settings_snapshot
+ )
+ if not use_in_auto:
+ continue
+
+ # Optional agent_enabled flag check prior to probe
+ if check_agent_enabled:
+ agent_enabled = config.get("agent_enabled")
+ if agent_enabled is None:
+ agent_enabled = get_setting_from_snapshot(
+ f"search.engine.web.{name}.agent_enabled",
+ True,
+ settings_snapshot=settings_snapshot,
+ )
+ if not agent_enabled:
+ logger.debug(f"Skipping {name} — disabled for research agent")
+ continue
+
+ # Egress policy check prior to network probe
+ if egress_context is not None:
+ if config.get("is_retriever"):
+ try:
+ from .retriever_registry import retriever_registry
+
+ meta = retriever_registry.get_metadata(name)
+ except Exception:
+ meta = None
+ decision = evaluate_retriever(
+ name, egress_context, metadata=meta
+ )
+ else:
+ decision = evaluate_engine(
+ name,
+ egress_context,
+ settings_snapshot=settings_snapshot,
+ metadata=config,
+ )
+ if not decision.allowed:
+ logger.debug(
+ f"Skipping {name} — disallowed by egress policy ({decision.reason})"
+ )
+ continue
+
+ # Runtime availability probe. Cheap (cached, single TCP connect at
+ # worst) and excludes engines whose backing service isn't reachable
+ # so the agent doesn't waste steps advertising broken tools.
+ # ``is_retriever`` entries go through the retriever registry's own
+ # ``is_available`` path — skip them here so we don't double-probe
+ # or fall back to the base class default for custom retriever
+ # classes that never subclass ``BaseSearchEngine``.
+ if not config.get("is_retriever", False):
+ if not _engine_class_is_available(name, config, settings_snapshot):
+ logger.debug(
+ f"Skipping {name} — runtime availability probe failed"
+ )
+ continue
+
eligible[name] = config
return eligible
+def _engine_class_is_available(
+ name: str,
+ config: Dict[str, Any],
+ settings_snapshot: Dict[str, Any],
+) -> bool:
+ """Load the engine class for ``config`` and call its ``is_available``.
+
+ Returns True (fail-open) on any error — the class load can legitimately
+ fail (bad module_path, missing dependency, sandbox import restrictions)
+ and we don't want ``list_eligible_engine_configs`` to mask real config
+ problems with an unrelated "engine unavailable" log line. The factory
+ will surface the real ``Failed to create search engine`` error when
+ (and only when) the caller actually tries to instantiate it.
+ """
+ from .search_engine_base import BaseSearchEngine
+
+ module_path = config.get("module_path")
+ class_name = config.get("class_name")
+ if not module_path or not class_name:
+ return True
+
+ try:
+ from ..security.module_whitelist import get_safe_module_class
+
+ engine_class = get_safe_module_class(module_path, class_name)
+ except Exception as exc:
+ logger.debug(
+ "Skipping availability probe for {} — could not load engine "
+ "class ({}: {})",
+ name,
+ type(exc).__name__,
+ exc,
+ )
+ return True
+
+ # Only subclasses of BaseSearchEngine get the ``is_available`` contract.
+ # Library / Collection / Retriever engines either subclass it (in which
+ # case the default ``True`` applies) or don't (also default True).
+ if not isinstance(engine_class, type) or not issubclass(
+ engine_class, BaseSearchEngine
+ ):
+ return True
+
+ try:
+ return bool(
+ engine_class.is_available(settings_snapshot=settings_snapshot)
+ )
+ except Exception as exc:
+ logger.debug(
+ "is_available raised for {} — treating as available ({})",
+ name,
+ type(exc).__name__,
+ )
+ return True
+
+
def get_available_engines(
settings_snapshot: Optional[Dict[str, Any]] = None,
use_api_key_services: bool = True,
@@ -358,25 +501,15 @@ def get_available_engines(
eligible = list_eligible_engine_configs(
settings_snapshot=settings_snapshot,
use_api_key_services=use_api_key_services,
+ check_auto_search=True,
)
excluded = set(exclude_engines) if exclude_engines else set()
- available: Dict[str, Any] = {}
- for name, config in eligible.items():
- if name in excluded:
- continue
-
- # Check use_in_auto_search setting (default False)
- auto_search_key = f"search.engine.web.{name}.use_in_auto_search"
- use_in_auto = get_setting_from_snapshot(
- auto_search_key, False, settings_snapshot=settings_snapshot
- )
- if not use_in_auto:
- continue
-
- available[name] = config
-
- return available
+ return {
+ name: config
+ for name, config in eligible.items()
+ if name not in excluded
+ }
def _resolve_api_key(
diff --git a/tests/advanced_search_system/filters/test_journal_reputation_coverage.py b/tests/advanced_search_system/filters/test_journal_reputation_coverage.py
index 0745d863ed..aa94e66feb 100644
--- a/tests/advanced_search_system/filters/test_journal_reputation_coverage.py
+++ b/tests/advanced_search_system/filters/test_journal_reputation_coverage.py
@@ -39,6 +39,7 @@ def _make_filter(
mock_model = MagicMock()
mock_engine = MagicMock()
+ mock_engine._is_available = engine_available
mock_engine.is_available = engine_available
with (
@@ -91,7 +92,7 @@ class TestInitErrors:
mock_model = MagicMock()
mock_engine = MagicMock()
- mock_engine.is_available = False
+ mock_engine._is_available = False
with patch(f"{MODULE}.create_search_engine", return_value=mock_engine):
# Should NOT raise — SearXNG is optional now
filt = JournalReputationFilter(
@@ -102,6 +103,30 @@ class TestInitErrors:
quality_reanalysis_period=timedelta(days=365),
)
assert filt is not None
+ assert filt._JournalReputationFilter__searxng_available is False
+
+ def test_searxng_real_engine_instance_unreachable(self):
+ """Verify that a real SearXNGSearchEngine with _is_available=False disables Tier 4."""
+ from local_deep_research.advanced_search_system.filters.journal_reputation_filter import (
+ JournalReputationFilter,
+ )
+ from local_deep_research.web_search_engines.engines.search_engine_searxng import (
+ SearXNGSearchEngine,
+ )
+
+ mock_model = MagicMock()
+ real_searxng = SearXNGSearchEngine.__new__(SearXNGSearchEngine)
+ real_searxng._is_available = False
+
+ with patch(f"{MODULE}.create_search_engine", return_value=real_searxng):
+ filt = JournalReputationFilter(
+ model=mock_model,
+ reliability_threshold=5,
+ max_context=3000,
+ exclude_non_published=False,
+ quality_reanalysis_period=timedelta(days=365),
+ )
+ assert filt._JournalReputationFilter__searxng_available is False
# ---------------------------------------------------------------------------
diff --git a/tests/search_engines/test_search_engine_searxng.py b/tests/search_engines/test_search_engine_searxng.py
index 61a96f38eb..84b06d7e15 100644
--- a/tests/search_engines/test_search_engine_searxng.py
+++ b/tests/search_engines/test_search_engine_searxng.py
@@ -165,7 +165,7 @@ class TestSearXNGAvailability:
)
engine = SearXNGSearchEngine()
- assert engine.is_available is True
+ assert engine._is_available is True
def test_instance_unavailable_when_error(self, monkeypatch):
"""Test that engine is marked unavailable on error response."""
@@ -182,7 +182,7 @@ class TestSearXNGAvailability:
)
engine = SearXNGSearchEngine()
- assert engine.is_available is False
+ assert engine._is_available is False
def test_instance_unavailable_when_connection_error(self, monkeypatch):
"""Test that engine is marked unavailable on connection error."""
@@ -198,7 +198,7 @@ class TestSearXNGAvailability:
)
engine = SearXNGSearchEngine()
- assert engine.is_available is False
+ assert engine._is_available is False
class TestSearXNGEngineType:
@@ -265,7 +265,7 @@ class TestSearXNGSearchExecution:
)
engine = SearXNGSearchEngine()
- engine.is_available = False
+ engine._is_available = False
previews = engine._get_previews("test query")
assert previews == []
@@ -277,7 +277,7 @@ class TestSearXNGSearchExecution:
)
engine = SearXNGSearchEngine()
- engine.is_available = False
+ engine._is_available = False
results = engine.run("test query")
assert results == []
@@ -289,7 +289,7 @@ class TestSearXNGSearchExecution:
)
engine = SearXNGSearchEngine()
- engine.is_available = False
+ engine._is_available = False
results = engine.results("test query")
assert results == []
@@ -555,7 +555,7 @@ class TestSearXNGSearchResults:
)
engine = SearXNGSearchEngine()
- engine.is_available = False
+ engine._is_available = False
results = engine._get_search_results("test")
assert results == []
@@ -754,7 +754,7 @@ class TestSearXNGGetFullContent:
)
engine = SearXNGSearchEngine()
- engine.is_available = False
+ engine._is_available = False
items = [{"title": "Test", "snippet": "Content"}]
results = engine._get_full_content(items)
diff --git a/tests/searxng/test_searxng.py b/tests/searxng/test_searxng.py
index 38f7e471cc..63f45d513c 100644
--- a/tests/searxng/test_searxng.py
+++ b/tests/searxng/test_searxng.py
@@ -126,7 +126,7 @@ class TestSearXNGSearch:
# Set required attributes without network calls
self.instance_url = "http://localhost:8080"
self.max_results = 10
- self.is_available = True
+ self._is_available = True
super(SearXNGSearchEngine, self).__init__(*args, **kwargs)
monkeypatch.setattr(SearXNGSearchEngine, "__init__", mock_init)
diff --git a/tests/web_search_engines/engines/test_search_engine_elasticsearch.py b/tests/web_search_engines/engines/test_search_engine_elasticsearch.py
index bfd90a4f0a..2d96d3766a 100644
--- a/tests/web_search_engines/engines/test_search_engine_elasticsearch.py
+++ b/tests/web_search_engines/engines/test_search_engine_elasticsearch.py
@@ -792,3 +792,223 @@ class TestProcessEsResponse:
assert previews[0]["score"] == 2.5
assert "content" in previews[0]["snippet"]
assert previews[1]["title"] == "Another Doc"
+
+
+class TestElasticsearchIsAvailable:
+ """Tests for ElasticsearchSearchEngine.is_available probe."""
+
+ def setup_method(self):
+ from local_deep_research.web_search_engines.engines.search_engine_elasticsearch import (
+ ElasticsearchSearchEngine,
+ )
+
+ ElasticsearchSearchEngine.clear_availability_cache()
+
+ def teardown_method(self):
+ from local_deep_research.web_search_engines.engines.search_engine_elasticsearch import (
+ ElasticsearchSearchEngine,
+ )
+
+ ElasticsearchSearchEngine.clear_availability_cache()
+
+ def test_is_available_cloud_id(self):
+ """cloud_id configuration returns True without probing."""
+ from local_deep_research.web_search_engines.engines.search_engine_elasticsearch import (
+ ElasticsearchSearchEngine,
+ )
+
+ snapshot = {
+ "search.engine.web.elasticsearch.default_params.cloud_id": "my_cloud_id:123"
+ }
+ assert ElasticsearchSearchEngine.is_available(snapshot) is True
+
+ def test_is_available_probe_success(self):
+ """Returns True when TCP probe succeeds."""
+ from local_deep_research.web_search_engines.engines.search_engine_elasticsearch import (
+ ElasticsearchSearchEngine,
+ )
+
+ with patch("socket.create_connection") as mock_conn:
+ mock_conn.return_value.__enter__.return_value = MagicMock()
+ snapshot = {
+ "search.engine.web.elasticsearch.default_params.hosts": [
+ "http://localhost:9200"
+ ]
+ }
+ assert ElasticsearchSearchEngine.is_available(snapshot) is True
+ mock_conn.assert_called_once_with(("localhost", 9200), timeout=1.0)
+
+ def test_is_available_probe_failure(self):
+ """Returns False when TCP probe raises OSError."""
+ from local_deep_research.web_search_engines.engines.search_engine_elasticsearch import (
+ ElasticsearchSearchEngine,
+ )
+
+ with patch(
+ "socket.create_connection",
+ side_effect=OSError("Connection refused"),
+ ):
+ snapshot = {
+ "search.engine.web.elasticsearch.default_params.hosts": [
+ "http://localhost:9200"
+ ]
+ }
+ assert ElasticsearchSearchEngine.is_available(snapshot) is False
+
+ def test_is_available_caching(self):
+ """Caches results for the TTL period."""
+ from local_deep_research.web_search_engines.engines.search_engine_elasticsearch import (
+ ElasticsearchSearchEngine,
+ )
+
+ with patch(
+ "socket.create_connection", side_effect=OSError("Refused")
+ ) as mock_conn:
+ snapshot = {
+ "search.engine.web.elasticsearch.default_params.hosts": [
+ "http://localhost:9200"
+ ]
+ }
+ assert ElasticsearchSearchEngine.is_available(snapshot) is False
+ assert ElasticsearchSearchEngine.is_available(snapshot) is False
+ # Should only attempt socket connection once due to TTL cache
+ assert mock_conn.call_count == 1
+
+ def test_is_available_dict_hosts(self):
+ """Handles list of dict hosts without raising TypeError."""
+ from local_deep_research.web_search_engines.engines.search_engine_elasticsearch import (
+ ElasticsearchSearchEngine,
+ )
+
+ with patch("socket.create_connection") as mock_conn:
+ mock_conn.return_value.__enter__.return_value = MagicMock()
+ snapshot = {
+ "search.engine.web.elasticsearch.default_params.hosts": [
+ {"host": "localhost", "port": 9201, "scheme": "http"}
+ ]
+ }
+ assert ElasticsearchSearchEngine.is_available(snapshot) is True
+ mock_conn.assert_called_once_with(("localhost", 9201), timeout=1.0)
+
+ def test_is_available_hosts_without_scheme(self):
+ """Parses hosts specified as 'host:port' strings."""
+ from local_deep_research.web_search_engines.engines.search_engine_elasticsearch import (
+ ElasticsearchSearchEngine,
+ )
+
+ with patch("socket.create_connection") as mock_conn:
+ mock_conn.return_value.__enter__.return_value = MagicMock()
+ snapshot = {
+ "search.engine.web.elasticsearch.default_params.hosts": [
+ "localhost:9200"
+ ]
+ }
+ assert ElasticsearchSearchEngine.is_available(snapshot) is True
+ mock_conn.assert_called_once_with(("localhost", 9200), timeout=1.0)
+
+ def test_is_available_cache_key_separation(self):
+ """Cache keys are separated across different host configurations."""
+ from local_deep_research.web_search_engines.engines.search_engine_elasticsearch import (
+ ElasticsearchSearchEngine,
+ )
+
+ with patch("socket.create_connection") as mock_conn:
+ mock_conn.return_value.__enter__.return_value = MagicMock()
+ snapshot1 = {
+ "search.engine.web.elasticsearch.default_params.hosts": [
+ "http://localhost:9200"
+ ]
+ }
+ snapshot2 = {
+ "search.engine.web.elasticsearch.default_params.hosts": [
+ "http://localhost:9201"
+ ]
+ }
+ assert ElasticsearchSearchEngine.is_available(snapshot1) is True
+ assert ElasticsearchSearchEngine.is_available(snapshot2) is True
+ assert mock_conn.call_count == 2
+
+ def test_is_available_multi_host_failover(self):
+ """Tries next host when first host connection fails."""
+ from local_deep_research.web_search_engines.engines.search_engine_elasticsearch import (
+ ElasticsearchSearchEngine,
+ )
+
+ success_mock = MagicMock()
+ with patch(
+ "socket.create_connection",
+ side_effect=[OSError("Connection refused"), success_mock],
+ ) as mock_conn:
+ snapshot = {
+ "search.engine.web.elasticsearch.default_params.hosts": [
+ "http://localhost:9200",
+ "http://127.0.0.1:9200",
+ ]
+ }
+ assert ElasticsearchSearchEngine.is_available(snapshot) is True
+ assert mock_conn.call_count == 2
+
+ def test_is_available_https_default_port(self):
+ """HTTPS scheme defaults to port 443."""
+ from local_deep_research.web_search_engines.engines.search_engine_elasticsearch import (
+ ElasticsearchSearchEngine,
+ )
+
+ with patch("socket.create_connection") as mock_conn:
+ mock_conn.return_value.__enter__.return_value = MagicMock()
+ snapshot = {
+ "search.engine.web.elasticsearch.default_params.hosts": [
+ "https://localhost"
+ ]
+ }
+ assert ElasticsearchSearchEngine.is_available(snapshot) is True
+ mock_conn.assert_called_once_with(("localhost", 443), timeout=1.0)
+
+ def test_is_available_positive_result_caching(self):
+ """Positive availability probe results are cached."""
+ from local_deep_research.web_search_engines.engines.search_engine_elasticsearch import (
+ ElasticsearchSearchEngine,
+ )
+
+ with patch("socket.create_connection") as mock_conn:
+ mock_conn.return_value.__enter__.return_value = MagicMock()
+ snapshot = {
+ "search.engine.web.elasticsearch.default_params.hosts": [
+ "http://localhost:9200"
+ ]
+ }
+ assert ElasticsearchSearchEngine.is_available(snapshot) is True
+ assert ElasticsearchSearchEngine.is_available(snapshot) is True
+ assert mock_conn.call_count == 1
+
+ def test_is_available_ssrf_validation_blocks_metadata(self):
+ """Metadata IP host fails SSRF validation and is skipped."""
+ from local_deep_research.web_search_engines.engines.search_engine_elasticsearch import (
+ ElasticsearchSearchEngine,
+ )
+
+ with patch("socket.create_connection") as mock_conn:
+ snapshot = {
+ "search.engine.web.elasticsearch.default_params.hosts": [
+ "http://169.254.169.254:9200"
+ ]
+ }
+ assert ElasticsearchSearchEngine.is_available(snapshot) is False
+ mock_conn.assert_not_called()
+
+ def test_is_available_outer_exception_fail_open(self):
+ """Unexpected exception in is_available causes fail open (returns True)."""
+ from local_deep_research.web_search_engines.engines.search_engine_elasticsearch import (
+ ElasticsearchSearchEngine,
+ )
+
+ with patch(
+ "local_deep_research.web_search_engines.engines.search_engine_elasticsearch.ElasticsearchSearchEngine._ensure_list",
+ side_effect=RuntimeError("Unexpected error"),
+ ):
+ snapshot = {
+ "search.engine.web.elasticsearch.default_params.hosts": [
+ "http://localhost:9200"
+ ]
+ }
+ assert ElasticsearchSearchEngine.is_available(snapshot) is True
diff --git a/tests/web_search_engines/engines/test_search_engine_searxng.py b/tests/web_search_engines/engines/test_search_engine_searxng.py
index eccdf363f6..7e06e6120d 100644
--- a/tests/web_search_engines/engines/test_search_engine_searxng.py
+++ b/tests/web_search_engines/engines/test_search_engine_searxng.py
@@ -59,7 +59,7 @@ class TestSearXNGSearchEngineInit:
max_results=10,
)
- assert engine.is_available is True
+ assert engine._is_available is True
assert engine.instance_url == "http://localhost:8080"
assert engine.max_results == 10
@@ -80,7 +80,7 @@ class TestSearXNGSearchEngineInit:
instance_url="http://localhost:8080",
)
- assert engine.is_available is False
+ assert engine._is_available is False
def test_init_with_connection_error(self):
"""Initialize handles connection errors gracefully."""
@@ -100,7 +100,7 @@ class TestSearXNGSearchEngineInit:
instance_url="http://localhost:8080",
)
- assert engine.is_available is False
+ assert engine._is_available is False
def test_init_strips_trailing_slash(self):
"""Initialize strips trailing slash from instance URL."""
diff --git a/tests/web_search_engines/test_search_engine_factory_coverage.py b/tests/web_search_engines/test_search_engine_factory_coverage.py
index 1df8d84215..07e16d6fdb 100644
--- a/tests/web_search_engines/test_search_engine_factory_coverage.py
+++ b/tests/web_search_engines/test_search_engine_factory_coverage.py
@@ -1462,3 +1462,77 @@ class TestProgrammaticModeContract:
f"per-instance AdaptiveRateLimitTracker, got "
f"{type(result.rate_tracker).__name__}"
)
+
+
+def test_factory_logging_checks_instance_is_available_attribute():
+ """Factory logging reads instance _is_available attribute if present."""
+ from local_deep_research.web_search_engines.search_engine_base import (
+ BaseSearchEngine,
+ )
+ from local_deep_research.web_search_engines.search_engine_factory import (
+ get_search,
+ )
+
+ class _MockEngine(BaseSearchEngine):
+ def __init__(self, **kwargs):
+ super().__init__()
+ self._is_available = False
+
+ def _get_previews(self, query):
+ return []
+
+ def _get_full_content(self, items):
+ return items
+
+ with _patches(
+ config_return={"mock_eng": _engine_config()},
+ class_return=_MockEngine,
+ ):
+ with patch(
+ "local_deep_research.web_search_engines.search_engine_factory.logger"
+ ) as mock_logger:
+ engine = get_search(
+ "mock_eng", Mock(), settings_snapshot={"a": "b"}
+ )
+ assert engine is not None
+ assert engine._is_available is False
+ # Verify logger logged false for availability flag
+ logged_avail = any(
+ "Engine availability flag: False" in str(call)
+ for call in mock_logger.info.call_args_list
+ )
+ assert logged_avail
+
+
+def test_factory_logging_passes_settings_snapshot_to_is_available():
+ """Factory logging passes settings_snapshot when calling engine.is_available."""
+ from local_deep_research.web_search_engines.search_engine_base import (
+ BaseSearchEngine,
+ )
+ from local_deep_research.web_search_engines.search_engine_factory import (
+ get_search,
+ )
+
+ received_snapshots = []
+
+ class _MockEngine(BaseSearchEngine):
+ @classmethod
+ def is_available(cls, settings_snapshot=None):
+ received_snapshots.append(settings_snapshot)
+ return True
+
+ def _get_previews(self, query):
+ return []
+
+ def _get_full_content(self, items):
+ return items
+
+ snapshot = {"my_key": "my_val"}
+ with _patches(
+ config_return={"mock_eng": _engine_config()},
+ class_return=_MockEngine,
+ ):
+ get_search("mock_eng", Mock(), settings_snapshot=snapshot)
+
+ assert len(received_snapshots) > 0
+ assert received_snapshots[-1] == snapshot
diff --git a/tests/web_search_engines/test_search_engines_config.py b/tests/web_search_engines/test_search_engines_config.py
index 4ca47e10cb..f3c66911fb 100644
--- a/tests/web_search_engines/test_search_engines_config.py
+++ b/tests/web_search_engines/test_search_engines_config.py
@@ -443,3 +443,163 @@ class TestDefaultSearchEngine:
default_search_engine(settings_snapshot=snapshot)
call_kwargs = mock_get_setting.call_args[1]
assert call_kwargs["settings_snapshot"] is snapshot
+
+
+class TestListEligibleEngineConfigsAvailability:
+ """Tests for runtime availability filtering in list_eligible_engine_configs."""
+
+ @patch(
+ "local_deep_research.web_search_engines.search_engines_config._engine_class_is_available"
+ )
+ @patch(
+ "local_deep_research.web_search_engines.search_engines_config.search_config"
+ )
+ def test_excludes_unavailable_engines(
+ self, mock_search_config, mock_is_avail
+ ):
+ from local_deep_research.web_search_engines.search_engines_config import (
+ list_eligible_engine_configs,
+ )
+
+ mock_search_config.return_value = {
+ "engine_a": {
+ "module_path": "a.b",
+ "class_name": "ClassA",
+ "requires_api_key": False,
+ },
+ "engine_b": {
+ "module_path": "a.b",
+ "class_name": "ClassB",
+ "requires_api_key": False,
+ },
+ }
+
+ def side_effect(name, config, snapshot):
+ return name == "engine_a"
+
+ mock_is_avail.side_effect = side_effect
+
+ snapshot = {"some": "setting"}
+ res = list_eligible_engine_configs(settings_snapshot=snapshot)
+
+ assert "engine_a" in res
+ assert "engine_b" not in res
+
+ @patch(
+ "local_deep_research.web_search_engines.search_engines_config._engine_class_is_available"
+ )
+ @patch(
+ "local_deep_research.web_search_engines.search_engines_config.search_config"
+ )
+ def test_pre_probe_filtering_agent_disabled(
+ self, mock_search_config, mock_is_avail
+ ):
+ """Disabled engines for agent are skipped before running runtime availability probe."""
+ from local_deep_research.web_search_engines.search_engines_config import (
+ list_eligible_engine_configs,
+ )
+
+ mock_search_config.return_value = {
+ "disabled_engine": {
+ "agent_enabled": False,
+ "requires_api_key": False,
+ },
+ "enabled_engine": {
+ "agent_enabled": True,
+ "requires_api_key": False,
+ },
+ }
+ mock_is_avail.return_value = True
+
+ res = list_eligible_engine_configs(
+ settings_snapshot={"some": "setting"}, check_agent_enabled=True
+ )
+
+ assert "enabled_engine" in res
+ assert "disabled_engine" not in res
+ # Availability probe should only have been called for the enabled engine
+ assert mock_is_avail.call_count == 1
+ assert mock_is_avail.call_args[0][0] == "enabled_engine"
+
+ @patch(
+ "local_deep_research.web_search_engines.search_engines_config._engine_class_is_available"
+ )
+ @patch(
+ "local_deep_research.web_search_engines.search_engines_config.search_config"
+ )
+ def test_pre_probe_filtering_auto_search_disabled(
+ self, mock_search_config, mock_is_avail
+ ):
+ """Engines disabled for auto search are skipped before running runtime availability probe."""
+ from local_deep_research.web_search_engines.search_engines_config import (
+ list_eligible_engine_configs,
+ )
+
+ mock_search_config.return_value = {
+ "auto_disabled": {
+ "requires_api_key": False,
+ },
+ "auto_enabled": {
+ "requires_api_key": False,
+ },
+ }
+ mock_is_avail.return_value = True
+
+ snapshot = {
+ "search.engine.web.auto_disabled.use_in_auto_search": False,
+ "search.engine.web.auto_enabled.use_in_auto_search": True,
+ }
+ res = list_eligible_engine_configs(
+ settings_snapshot=snapshot, check_auto_search=True
+ )
+
+ assert "auto_enabled" in res
+ assert "auto_disabled" not in res
+ assert mock_is_avail.call_count == 1
+ assert mock_is_avail.call_args[0][0] == "auto_enabled"
+
+ @patch(
+ "local_deep_research.web_search_engines.search_engines_config._engine_class_is_available"
+ )
+ @patch(
+ "local_deep_research.web_search_engines.search_engines_config.search_config"
+ )
+ def test_strict_egress_retains_primary_engine(
+ self, mock_search_config, mock_is_avail
+ ):
+ """Under STRICT egress scope, the primary engine passes egress filter and is retained."""
+ from local_deep_research.security.egress.policy import (
+ EgressContext,
+ EgressScope,
+ )
+ from local_deep_research.web_search_engines.search_engines_config import (
+ list_eligible_engine_configs,
+ )
+
+ mock_search_config.return_value = {
+ "searxng": {
+ "requires_api_key": False,
+ "module_path": "local_deep_research.web_search_engines.engines.search_engine_searxng",
+ "class_name": "SearXNGSearchEngine",
+ },
+ "arxiv": {
+ "requires_api_key": False,
+ "module_path": "local_deep_research.web_search_engines.engines.search_engine_arxiv",
+ "class_name": "ArxivSearchEngine",
+ },
+ }
+ mock_is_avail.return_value = True
+
+ egress_ctx = EgressContext(
+ scope=EgressScope.STRICT,
+ primary_engine="searxng",
+ require_local_llm=False,
+ require_local_embeddings=False,
+ )
+ snapshot = {"some": "setting"}
+ res = list_eligible_engine_configs(
+ settings_snapshot=snapshot, egress_context=egress_ctx
+ )
+
+ assert "searxng" in res
+ assert "arxiv" not in res