~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
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.pyindex 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.pyindex 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 Noneand 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.pyindex 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 jsonfrom ...security.secure_logging import logger+import time as _timefrom typing import Any, Dict, List, Optionalfrom 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.pyindex 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 = Trueelse:- self.is_available = False+ self._is_available = Falselogger.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 = Falsesafe_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 parameterslogger.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_itemsif 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.pyindex 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.pyindex 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 enginediff --git a/src/local_deep_research/web_search_engines/search_engines_config.py b/src/local_deep_research/web_search_engines/search_engines_config.pyindex 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 theregistry 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 keyare 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] = configreturn 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.pyindex 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_availablemock_engine.is_available = engine_availablewith (@@ -91,7 +92,7 @@ class TestInitErrors:mock_model = MagicMock()mock_engine = MagicMock()- mock_engine.is_available = False+ mock_engine._is_available = Falsewith patch(f"{MODULE}.create_search_engine", return_value=mock_engine):# Should NOT raise — SearXNG is optional nowfilt = 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.pyindex 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 Truedef 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 Falsedef 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 Falseclass TestSearXNGEngineType:@@ -265,7 +265,7 @@ class TestSearXNGSearchExecution:)engine = SearXNGSearchEngine()- engine.is_available = False+ engine._is_available = Falsepreviews = engine._get_previews("test query")assert previews == []@@ -277,7 +277,7 @@ class TestSearXNGSearchExecution:)engine = SearXNGSearchEngine()- engine.is_available = False+ engine._is_available = Falseresults = engine.run("test query")assert results == []@@ -289,7 +289,7 @@ class TestSearXNGSearchExecution:)engine = SearXNGSearchEngine()- engine.is_available = False+ engine._is_available = Falseresults = engine.results("test query")assert results == []@@ -555,7 +555,7 @@ class TestSearXNGSearchResults:)engine = SearXNGSearchEngine()- engine.is_available = False+ engine._is_available = Falseresults = engine._get_search_results("test")assert results == []@@ -754,7 +754,7 @@ class TestSearXNGGetFullContent:)engine = SearXNGSearchEngine()- engine.is_available = False+ engine._is_available = Falseitems = [{"title": "Test", "snippet": "Content"}]results = engine._get_full_content(items)diff --git a/tests/searxng/test_searxng.py b/tests/searxng/test_searxng.pyindex 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 callsself.instance_url = "http://localhost:8080"self.max_results = 10- self.is_available = True+ self._is_available = Truesuper(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.pyindex 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.5assert "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 Truediff --git a/tests/web_search_engines/engines/test_search_engine_searxng.py b/tests/web_search_engines/engines/test_search_engine_searxng.pyindex 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 Trueassert 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 Falsedef 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 Falsedef 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.pyindex 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] == snapshotdiff --git a/tests/web_search_engines/test_search_engines_config.py b/tests/web_search_engines/test_search_engines_config.pyindex 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