~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
"""Shared helpers for research-service worker tests.
These previously lived in ``test_research_service_coverage_gaps.py``. The
FastAPI migration deleted that module because its *assertions* targeted the
Flask-era worker, but its *helpers* are still needed by
``test_research_service_search_limit_precedence.py``. Keeping them in a plain
sibling module (the pattern used by ``tests/notes/helpers.py``) means they no
longer disappear when a test module is retired.
"""
from contextlib import contextmanager, ExitStack
from functools import wraps
from unittest.mock import MagicMock, create_autospec, patch
from local_deep_research.web.services import research_service
# Module paths used as ``unittest.mock.patch`` targets.
MODULE = "local_deep_research.web.services.research_service"
RESEARCH_STATE_MOD = "local_deep_research.web.research_state"
GLOBALS_MOD = "local_deep_research.web.routes.globals"
THREAD_SETTINGS_MOD = "local_deep_research.config.thread_settings"
SETTINGS_LOGGER_MOD = "local_deep_research.settings.logger"
QUEUE_PROC_MOD = "local_deep_research.web.queue.processor_v2"
def _fake_session_ctx(session=None):
"""Return a context manager factory that yields a mock session."""
if session is None:
session = MagicMock()
@contextmanager
def ctx(username=None):
yield session
return ctx
def _make_mock_research(status=None, research_meta=None):
"""Build a minimal ResearchHistory mock."""
r = MagicMock()
r.status = status
r.research_meta = research_meta
r.created_at = "2024-01-01T00:00:00"
r.report_content = None
return r
def _get_raw_run_research_process():
"""Run the unwrapped worker while restoring the caller's egress context.
These tests intentionally skip thread_cleanup, which normally clears
the worker's active context. Preserve any enclosing context and prevent
a mocked run from contaminating policy checks later in the same process.
"""
from local_deep_research.security.egress.audit_hook import (
clear_active_context,
get_active_context,
set_active_context,
)
from local_deep_research.web.services.research_service import (
run_research_process,
)
# @log_for_research and @thread_cleanup, outermost first.
raw_worker = run_research_process.__wrapped__.__wrapped__
@wraps(raw_worker)
def isolated_worker(*args, **kwargs):
previous = get_active_context()
try:
return raw_worker(*args, **kwargs)
finally:
if previous is None:
clear_active_context()
else:
set_active_context(previous)
return isolated_worker
def _base_run_patches(mock_session=None):
"""Return a dict of patches needed for run_research_process tests."""
if mock_session is None:
mock_session = MagicMock()
mock_research = _make_mock_research(research_meta={})
mock_session.query.return_value.filter_by.return_value.first.return_value = mock_research
return {
f"{MODULE}.get_user_db_session": _fake_session_ctx(mock_session),
f"{MODULE}.handle_termination": MagicMock(),
f"{MODULE}.cleanup_research_resources": MagicMock(),
f"{MODULE}.set_search_context": MagicMock(),
# Socket isolation. The Flask-era ``SocketIOService`` class is gone;
# the FastAPI worker emits through these module-level socketio_asgi
# aliases plus the ``_socket_emitter`` adapter singleton.
#
# autospec, NOT a bare MagicMock: a plain mock accepts ANY signature,
# so when ``emit_to_subscribers`` gained a required ``owner`` kwarg
# these patches happily swallowed both the calls that forgot it and
# the calls that passed it to an adapter that did not accept it. Every
# such call site sits inside a swallowing ``except``, so the suite
# stayed green while live progress delivery was silently broken.
# autospec makes the mock enforce the real signature, turning that
# class of break into a test failure.
f"{MODULE}._sio_emit": create_autospec(
research_service._sio_emit, spec_set=True
),
f"{MODULE}._sio_remove": create_autospec(
research_service._sio_remove, spec_set=True
),
f"{MODULE}._socket_emitter": create_autospec(
research_service._socket_emitter, spec_set=True
),
f"{MODULE}.calculate_duration": MagicMock(return_value=5),
f"{MODULE}.ErrorReportGenerator": MagicMock(
return_value=MagicMock(
generate_error_report=MagicMock(return_value="error report")
)
),
# ``run_research_process`` imports research state straight from
# ``research_state``; patching the ``routes.globals`` shim does not
# reach it, because the shim bound its own names at import time.
f"{RESEARCH_STATE_MOD}.is_termination_requested": MagicMock(
return_value=False
),
f"{RESEARCH_STATE_MOD}.is_research_active": MagicMock(
return_value=False
),
f"{RESEARCH_STATE_MOD}.update_progress_and_check_active": MagicMock(
return_value=(5, True)
),
# ``_make_chat_stream_callback`` still resolves through the shim on
# purpose (see the comment at its import site), so that target has to
# be neutralised too.
f"{GLOBALS_MOD}.is_termination_requested": MagicMock(
return_value=False
),
f"{SETTINGS_LOGGER_MOD}.log_settings": MagicMock(),
f"{THREAD_SETTINGS_MOD}.set_settings_context": MagicMock(),
f"{QUEUE_PROC_MOD}.queue_processor": MagicMock(),
}
# ---------------------------------------------------------------------------
# Quick-mode error-classification / synthesis-fallback harnesses.
#
# ``run_research_process``'s error handling for a failed search
# (``except Exception as search_error`` around ``system.analyze_topic()``,
# research_service.py ~1670-1730) and for an error-shaped *result*
# (the ``formatted_findings.startswith("Error:")`` branch, ~1736-1900)
# are both several hundred lines deep inside one 2000+ line function and
# are not exposed as standalone symbols. Several test modules used to
# re-implement (a stripped copy of) that logic locally and assert on the
# copy -- see ADR-0010. These two helpers drive the REAL function to the
# real branch and read back an observable side effect instead:
#
# * ``run_quick_mode_with_search_error`` makes ``analyze_topic`` raise;
# the classified, user-facing message is read back from the
# ``ErrorReportGenerator.generate_error_report(error_message=...)``
# call the outer ``except Exception as e:`` handler makes.
# * ``run_quick_mode_with_analyze_result`` makes ``analyze_topic``
# return a results dict; the post-fallback ``clean_markdown`` text is
# read back from the ``formatter.format_document_split(...)`` call
# research_service.py makes right before persisting the report. When
# the fallback logic gives up entirely, ``ErrorReportGenerator`` fires
# instead (mirroring the first helper), so both are captured.
# ---------------------------------------------------------------------------
def _egress_and_search_patches():
"""Patches shared by both quick-mode harnesses below."""
return [
patch(
"local_deep_research.config.search_config.factory_get_search",
MagicMock(return_value=MagicMock()),
),
patch(
"local_deep_research.security.egress.policy.context_from_snapshot",
return_value=MagicMock(),
),
patch(
"local_deep_research.security.egress.run_classification.audit_run_from_snapshot",
return_value=MagicMock(allowed=True),
),
]
def run_quick_mode_with_search_error(error_message: str) -> str:
"""Drive run_research_process('quick') with analyze_topic raising
``Exception(error_message)`` and return the classified, user-facing
message research_service builds for it (via ErrorReportGenerator).
This exercises the REAL two-stage classification in
research_service.py: the inner ``except Exception as search_error``
turns the raw message into ``RuntimeError("... (Error type: X)")``,
and the outer ``except Exception as e`` turns that into the final
user-facing string, which is what gets persisted via
``ErrorReportGenerator.generate_error_report(error_message=...)``.
"""
system = MagicMock()
system.analyze_topic.side_effect = Exception(error_message)
error_gen_instance = MagicMock(
generate_error_report=MagicMock(return_value="error report")
)
patches = _base_run_patches()
patches[f"{MODULE}.get_llm"] = MagicMock(return_value=MagicMock())
patches[f"{MODULE}.AdvancedSearchSystem"] = MagicMock(return_value=system)
patches[f"{MODULE}.ErrorReportGenerator"] = MagicMock(
return_value=error_gen_instance
)
snapshot = {
"llm.provider": "ollama",
"llm.model": "m",
"search.tool": "searxng",
}
with ExitStack() as stack:
for cm in _egress_and_search_patches():
stack.enter_context(cm)
for target, mock_obj in patches.items():
stack.enter_context(patch(target, mock_obj))
_get_raw_run_research_process()(
1,
"test query",
"quick",
username="user1",
settings_snapshot=snapshot,
search_engine="searxng",
)
assert error_gen_instance.generate_error_report.called, (
"ErrorReportGenerator.generate_error_report was never called -- "
"the search-error path did not run as expected"
)
return error_gen_instance.generate_error_report.call_args.kwargs[
"error_message"
]
def run_quick_mode_with_analyze_result(results: dict) -> dict:
"""Drive run_research_process('quick') with analyze_topic returning
``results`` and report back what happened to it.
Returns a dict with exactly one of:
* ``{"error_report_message": <str>}`` -- the fallback logic could
not recover; ErrorReportGenerator ran. Checked first because,
when it fires, its (mocked) return value is what
``clean_markdown`` ends up holding too -- so this branch must
take priority over the formatter-call check below or a fully-
exhausted-fallback case would be misreported as recovered.
* ``{"clean_markdown": <str>}`` -- the fallback logic recovered
(or there was no error to begin with) and this is the text handed
to the citation formatter for the final report.
"""
system = MagicMock()
system.analyze_topic.return_value = results
system.all_links_of_system = []
formatter = MagicMock()
formatter.format_document_split.return_value = ("answer", [], False)
formatter.apply_inline_hyperlinks.return_value = "answer"
error_gen_instance = MagicMock(
generate_error_report=MagicMock(return_value="error report")
)
patches = _base_run_patches()
patches[f"{MODULE}.get_llm"] = MagicMock(return_value=MagicMock())
patches[f"{MODULE}.AdvancedSearchSystem"] = MagicMock(return_value=system)
patches[f"{MODULE}.get_citation_formatter"] = MagicMock(
return_value=formatter
)
patches[f"{MODULE}.ErrorReportGenerator"] = MagicMock(
return_value=error_gen_instance
)
snapshot = {
"llm.provider": "ollama",
"llm.model": "m",
"search.tool": "searxng",
}
with ExitStack() as stack:
for cm in _egress_and_search_patches():
stack.enter_context(cm)
for target, mock_obj in patches.items():
stack.enter_context(patch(target, mock_obj))
_get_raw_run_research_process()(
1,
"test query",
"quick",
username="user1",
settings_snapshot=snapshot,
search_engine="searxng",
)
if error_gen_instance.generate_error_report.called:
return {
"error_report_message": (
error_gen_instance.generate_error_report.call_args.kwargs[
"error_message"
]
)
}
if formatter.format_document_split.called:
return {
"clean_markdown": formatter.format_document_split.call_args[0][0]
}
raise AssertionError(
"neither the citation formatter nor ErrorReportGenerator ran -- "
"the quick-mode output path did not complete as expected"
)