~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
from contextlib import nullcontext
from unittest.mock import Mock, patch
import pytest
from sqlalchemy import create_engine
from sqlalchemy.orm import Session, sessionmaker
from local_deep_research.constants import ResearchStatus
from local_deep_research.database.models.active_research import (
UserActiveResearch,
)
from local_deep_research.database.models.queue import QueueStatus, TaskMetadata
from local_deep_research.database.models.queued_research import QueuedResearch
from local_deep_research.database.models.research import ResearchHistory
from local_deep_research.database.queue_service import UserQueueService
from local_deep_research.exceptions import DuplicateResearchError
from local_deep_research.web.queue.processor_v2 import QueueProcessorV2
MODULE = "local_deep_research.web.queue.processor_v2"
@pytest.fixture()
def db_session() -> Session:
engine = create_engine("sqlite:///:memory:")
QueuedResearch.__table__.create(engine)
QueueStatus.__table__.create(engine)
TaskMetadata.__table__.create(engine)
ResearchHistory.__table__.create(engine)
UserActiveResearch.__table__.create(engine)
session = sessionmaker(bind=engine)()
yield session
session.close()
engine.dispose()
def _persist_queued_research(
db_session: Session,
research_id: str,
settings_snapshot,
) -> QueuedResearch:
queued = QueuedResearch(
username="alice",
research_id=research_id,
query="persisted override validation",
mode="quick",
position=1,
settings_snapshot=settings_snapshot,
)
db_session.add_all(
[
queued,
ResearchHistory(
id=research_id,
query=queued.query,
mode=queued.mode,
status=ResearchStatus.QUEUED,
created_at="2026-07-31T00:00:00+00:00",
),
]
)
db_session.commit()
return queued
INVALID_PERSISTED_OVERRIDES = (
pytest.param(
{
"submission": {"max_results": 0},
"submission_overrides": ["max_results"],
"settings_snapshot": {},
},
id="wrapped-max-results",
),
pytest.param(
{
"submission": {"time_period": "week"},
"submission_overrides": ["time_period"],
"settings_snapshot": {},
},
id="wrapped-time-period",
),
pytest.param({"max_results": 51}, id="legacy-flat-max-results"),
pytest.param({"time_period": "week"}, id="legacy-flat-time-period"),
)
@pytest.mark.parametrize("settings_snapshot", INVALID_PERSISTED_OVERRIDES)
def test_invalid_persisted_overrides_are_rejected_before_claim_and_spawn(
db_session: Session, settings_snapshot
) -> None:
# Given: a queued record persisted by an older or malformed submission.
from local_deep_research import exceptions
research_id = "invalid-persisted"
queued = _persist_queued_research(
db_session, research_id, settings_snapshot
)
processor = QueueProcessorV2()
# When: direct queue dispatch reconstructs its runtime overrides.
with patch(
f"{MODULE}.start_research_process", return_value=Mock(ident=1)
) as start:
with pytest.raises(
getattr(
exceptions, "InvalidQueuedResearchOverridesError", ValueError
)
):
processor._start_research(db_session, "alice", "password", queued)
# Then: no IN_PROGRESS claim or process can have been created.
assert (
db_session.get(ResearchHistory, research_id).status
== ResearchStatus.QUEUED
)
start.assert_not_called()
assert (
db_session.query(UserActiveResearch)
.filter_by(research_id=research_id)
.first()
is None
)
@pytest.mark.parametrize(
("max_results", "time_period"),
((1, "d"), (50, "all")),
ids=("minimum-day", "maximum-all-time"),
)
def test_valid_persisted_override_boundaries_reach_the_process(
db_session: Session, max_results: int, time_period: str
) -> None:
# Given: a wrapped record with explicit canonical boundary overrides.
queued = _persist_queued_research(
db_session,
f"valid-{max_results}-{time_period}",
{
"submission": {
"max_results": max_results,
"time_period": time_period,
},
"submission_overrides": ["max_results", "time_period"],
"settings_snapshot": {},
},
)
# When: the persisted record starts.
with patch(
f"{MODULE}.start_research_process", return_value=Mock(ident=2)
) as start:
QueueProcessorV2()._start_research(
db_session, "alice", "password", queued
)
# Then: validation permits and preserves both boundary values.
assert start.call_args.kwargs["max_results"] == max_results
assert start.call_args.kwargs["time_period"] == time_period
def test_wrapped_non_effective_invalid_values_remain_deferred(
db_session: Session,
) -> None:
# Given: values that look invalid but were not submitted as overrides.
queued = _persist_queued_research(
db_session,
"deferred-values",
{
"submission": {
"model": "queued-model",
"max_results": 0,
"time_period": "week",
},
"submission_overrides": ["model"],
"settings_snapshot": {},
},
)
# When: queue dispatch reconstructs only effective submission overrides.
with patch(
f"{MODULE}.start_research_process", return_value=Mock(ident=3)
) as start:
QueueProcessorV2()._start_research(
db_session, "alice", "password", queued
)
# Then: deferred snapshot values neither reject nor override runtime defaults.
call_kwargs = start.call_args.kwargs
assert call_kwargs["model"] == "queued-model"
assert "max_results" not in call_kwargs
assert "time_period" not in call_kwargs
def test_duplicate_status_precedes_persisted_override_validation(
db_session: Session,
) -> None:
# Given: an already-started record with otherwise invalid persisted data.
queued = _persist_queued_research(
db_session,
"duplicate-precedence",
{
"submission": {"max_results": 0},
"submission_overrides": ["max_results"],
"settings_snapshot": {},
},
)
db_session.get(
ResearchHistory, "duplicate-precedence"
).status = ResearchStatus.IN_PROGRESS
db_session.commit()
processor = QueueProcessorV2()
# When: the queue processor re-enters dispatch for the stale row.
with patch(f"{MODULE}.start_research_process") as start:
with pytest.raises(DuplicateResearchError):
processor._start_research(db_session, "alice", "password", queued)
# Then: duplicate cleanup retains its existing precedence and never spawns.
assert (
db_session.get(ResearchHistory, "duplicate-precedence").status
== ResearchStatus.IN_PROGRESS
)
start.assert_not_called()
def test_invalid_persisted_row_is_terminal_without_a_retry_or_spawn(
db_session: Session,
) -> None:
# Given: a queued task with a stale retry count and an invalid effective override.
research_id = "invalid-terminal"
_persist_queued_research(
db_session,
research_id,
{
"submission": {"max_results": 0},
"submission_overrides": ["max_results"],
"settings_snapshot": {},
},
)
db_session.add_all(
[
TaskMetadata(
task_id=research_id, status="queued", task_type="research"
),
QueueStatus(active_tasks=0, queued_tasks=1),
]
)
db_session.commit()
processor = QueueProcessorV2()
processor._spawn_retry_counts[research_id] = 2
# When: normal queue dispatch reaches the invalid persisted row.
with (
patch(
f"{MODULE}.start_research_process",
side_effect=AssertionError(
"invalid persisted overrides must not spawn"
),
) as start,
patch(
f"{MODULE}.get_user_db_session",
return_value=nullcontext(db_session),
),
patch(
f"{MODULE}.send_research_failed_notification_from_session"
) as send_failed,
patch.object(
processor,
"notify_research_failed",
wraps=processor.notify_research_failed,
) as notify_failed,
patch.object(
processor,
"_bump_spawn_retry_count",
wraps=processor._bump_spawn_retry_count,
) as bump_retry,
):
processor._start_queued_researches(
db_session, UserQueueService(db_session), "alice", "password", 1
)
# Then: invalid data is terminal, while generic retry/capacity behavior stays untouched.
assert start.call_count == bump_retry.call_count == 0
assert research_id not in processor._spawn_retry_counts
research = db_session.get(ResearchHistory, research_id)
metadata = db_session.get(TaskMetadata, research_id)
queued_row = (
db_session.query(QueuedResearch)
.filter_by(research_id=research_id)
.first()
)
assert (research.status, metadata.status) == 2 * (ResearchStatus.FAILED,)
assert queued_row is None
notify_failed.assert_called_once()
assert notify_failed.call_args.kwargs["research_id"] == research_id
send_failed.assert_called_once()