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.

test(strategies): target cancellation checks by context slug instead of callback ordinals (#5121)

LearningCircuitb1d60d565fba
diff --git a/changelog.d/+cancellation-check-context.misc.md b/changelog.d/+cancellation-check-context.misc.md
new file mode 100644
index 0000000000..69c92f7d1e
--- /dev/null
+++ b/changelog.d/+cancellation-check-context.misc.md
@@ -0,0 +1 @@
+Cancellation checks now tag their call site: `BaseSearchStrategy.check_termination()` accepts an optional `context` slug (e.g. `"pre_synthesis"`) that is included in the progress-callback metadata, and all 14 call sites across the six strategies pass one. The cancellation regression tests target these context slugs instead of counting callback invocations, so they no longer silently shift to a different check when a progress emit or check is added earlier in a strategy's flow. Follow-up to #5092; also fixes the topic-organization refinement-loop test, which previously cancelled at an unrelated earlier callback and never actually reached the refinement-loop check.
diff --git a/src/local_deep_research/advanced_search_system/strategies/base_strategy.py b/src/local_deep_research/advanced_search_system/strategies/base_strategy.py
index 8f7a5d45c0..f97c1beeb6 100644
--- a/src/local_deep_research/advanced_search_system/strategies/base_strategy.py
+++ b/src/local_deep_research/advanced_search_system/strategies/base_strategy.py
@@ -10,6 +10,19 @@ from loguru import logger
from ...utilities.type_utils import unwrap_setting
+# Context slugs for check_termination() call sites. Passed as the
+# ``context`` argument and surfaced in the callback metadata; tests import
+# them to cancel at one specific check. Keep source and tests on these
+# constants rather than repeating the literals.
+CHECK_CONTEXT_ENTRY = "entry"
+CHECK_CONTEXT_ITERATION_START = "iteration_start"
+CHECK_CONTEXT_POST_SEARCH = "post_search"
+CHECK_CONTEXT_PRE_SYNTHESIS = "pre_synthesis"
+CHECK_CONTEXT_PRE_ANALYSIS = "pre_analysis"
+CHECK_CONTEXT_REFINEMENT_LOOP = "refinement_loop"
+CHECK_CONTEXT_AGENT_STREAM = "agent_stream"
+CHECK_CONTEXT_FALLBACK_SYNTHESIS = "fallback_synthesis"
+
class BaseSearchStrategy(ABC):
"""Abstract base class for all search strategies."""
@@ -83,7 +96,7 @@ class BaseSearchStrategy(ABC):
"""Set a callback function to receive progress updates."""
self.progress_callback = callback
- def check_termination(self) -> None:
+ def check_termination(self, context: str | None = None) -> None:
"""Check if the research has been cancelled.
Reuses the existing ``progress_callback`` rather than a dedicated
@@ -97,13 +110,23 @@ class BaseSearchStrategy(ABC):
The callback in ``research_service.py`` recognises the
``"termination_check"`` phase and returns immediately after the
flag check -- no UI logging or socket emission occurs.
+
+ Args:
+ context: Slug naming the call site — one of the module-level
+ ``CHECK_CONTEXT_*`` constants (e.g.
+ ``CHECK_CONTEXT_PRE_SYNTHESIS``). Included in the callback
+ metadata so tests and diagnostics can target one specific
+ check instead of counting callback invocations.
"""
if self.progress_callback:
logger.debug("Checking termination status")
+ metadata: dict[str, Any] = {"phase": "termination_check"}
+ if context:
+ metadata["context"] = context
self.progress_callback(
"Checking termination status",
None,
- {"phase": "termination_check"},
+ metadata,
)
def _update_progress(
diff --git a/src/local_deep_research/advanced_search_system/strategies/focused_iteration_strategy.py b/src/local_deep_research/advanced_search_system/strategies/focused_iteration_strategy.py
index 261181f42b..17c521f37a 100644
--- a/src/local_deep_research/advanced_search_system/strategies/focused_iteration_strategy.py
+++ b/src/local_deep_research/advanced_search_system/strategies/focused_iteration_strategy.py
@@ -35,7 +35,12 @@ from ..candidate_exploration import ProgressiveExplorer
from ..findings.repository import FindingsRepository
from ..parallel_search import run_parallel_searches
from ..questions import BrowseCompQuestionGenerator
-from .base_strategy import BaseSearchStrategy
+from .base_strategy import (
+ BaseSearchStrategy,
+ CHECK_CONTEXT_ITERATION_START,
+ CHECK_CONTEXT_POST_SEARCH,
+ CHECK_CONTEXT_PRE_SYNTHESIS,
+)
class FocusedIterationStrategy(BaseSearchStrategy):
@@ -168,7 +173,7 @@ class FocusedIterationStrategy(BaseSearchStrategy):
# Main iteration loop
for iteration in range(1, self.max_iterations + 1):
# Check cancellation before each iteration to avoid 30-50s lag between Stop click and actual halt.
- self.check_termination()
+ self.check_termination(CHECK_CONTEXT_ITERATION_START)
iteration_progress = 10 + (iteration - 1) * (
80 / self.max_iterations
)
@@ -241,7 +246,7 @@ class FocusedIterationStrategy(BaseSearchStrategy):
)
# Check cancellation to prevent verification searches adding 10-30s after Stop.
- self.check_termination()
+ self.check_termination(CHECK_CONTEXT_POST_SEARCH)
# Log results but don't send progress update to avoid jumps
logger.info(
@@ -317,7 +322,7 @@ class FocusedIterationStrategy(BaseSearchStrategy):
self.all_links_of_system.extend(self.all_search_results)
# Check cancellation before final synthesis to prevent 10-30s delay after Stop.
- self.check_termination()
+ self.check_termination(CHECK_CONTEXT_PRE_SYNTHESIS)
# Final synthesis (like source-based - trust the LLM!)
self._update_progress(
diff --git a/src/local_deep_research/advanced_search_system/strategies/followup/enhanced_contextual_followup.py b/src/local_deep_research/advanced_search_system/strategies/followup/enhanced_contextual_followup.py
index 35a91303c2..48f5655e62 100644
--- a/src/local_deep_research/advanced_search_system/strategies/followup/enhanced_contextual_followup.py
+++ b/src/local_deep_research/advanced_search_system/strategies/followup/enhanced_contextual_followup.py
@@ -8,7 +8,10 @@ past research context, reformulates questions, and reuses sources effectively.
from typing import Dict, List, Optional, Any
from loguru import logger
-from ..base_strategy import BaseSearchStrategy
+from ..base_strategy import (
+ BaseSearchStrategy,
+ CHECK_CONTEXT_ENTRY,
+)
from ...filters.followup_relevance_filter import FollowUpRelevanceFilter
from ...knowledge.followup_context_manager import FollowUpContextHandler
from ...questions.followup.simple_followup_question import (
@@ -145,7 +148,7 @@ class EnhancedContextualFollowUpStrategy(BaseSearchStrategy):
# user a chance to bail before we pay for the
# ``generate_contextualized_query`` call (10-20 s) and the
# delegate strategy's own research below.
- self.check_termination()
+ self.check_termination(CHECK_CONTEXT_ENTRY)
# Update the context with the actual follow-up query
self.full_context["follow_up_query"] = query
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 95527ce181..766b54bf54 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
@@ -26,7 +26,12 @@ from ...citation_handler import CitationHandler
from ...security import sanitize_error_for_client
from ...utilities.thread_context import get_search_context, search_context
from ..tools.fetch import FETCH_MODES, build_fetch_tool
-from .base_strategy import BaseSearchStrategy
+from .base_strategy import (
+ BaseSearchStrategy,
+ CHECK_CONTEXT_AGENT_STREAM,
+ CHECK_CONTEXT_ENTRY,
+ CHECK_CONTEXT_FALLBACK_SYNTHESIS,
+)
# ---------------------------------------------------------------------------
# Constants
@@ -1194,7 +1199,7 @@ class LangGraphAgentStrategy(BaseSearchStrategy):
5,
{"phase": "init", "type": "milestone", "query": query[:100]},
)
- self.check_termination()
+ self.check_termination(CHECK_CONTEXT_ENTRY)
# Build tools (overall_query feeds summary-mode fetch tools)
tools = self._build_tools(overall_query=query)
@@ -1325,7 +1330,7 @@ class LangGraphAgentStrategy(BaseSearchStrategy):
config,
stream_mode="updates",
):
- self.check_termination()
+ self.check_termination(CHECK_CONTEXT_AGENT_STREAM)
if "agent" in chunk or "model" in chunk:
node_key = "agent" if "agent" in chunk else "model"
@@ -1467,7 +1472,7 @@ class LangGraphAgentStrategy(BaseSearchStrategy):
# early check, a cancel that arrived during the error path would
# have to wait for the synthesis LLM call to complete before
# terminating.
- self.check_termination()
+ self.check_termination(CHECK_CONTEXT_FALLBACK_SYNTHESIS)
results = self.collector.results
if not results:
diff --git a/src/local_deep_research/advanced_search_system/strategies/news_strategy.py b/src/local_deep_research/advanced_search_system/strategies/news_strategy.py
index 469de8d139..c8de13b6c0 100644
--- a/src/local_deep_research/advanced_search_system/strategies/news_strategy.py
+++ b/src/local_deep_research/advanced_search_system/strategies/news_strategy.py
@@ -7,7 +7,11 @@ from typing import List, Dict, Any, Optional
from datetime import datetime, UTC
from loguru import logger
-from .base_strategy import BaseSearchStrategy
+from .base_strategy import (
+ BaseSearchStrategy,
+ CHECK_CONTEXT_ENTRY,
+ CHECK_CONTEXT_PRE_ANALYSIS,
+)
from ..questions.news_question import NewsQuestionGenerator
from ...database.thread_local_session import thread_cleanup
from ...utilities.json_utils import extract_json
@@ -222,7 +226,7 @@ Ensure variety across different categories when possible.
# Check cancellation before any work — the news strategy runs a
# single iteration so without an early check a cancel has to wait
# for question generation + every search + the analysis LLM call.
- self.check_termination()
+ self.check_termination(CHECK_CONTEXT_ENTRY)
# Generate news-specific search queries
questions = self.generate_questions(query, "")
@@ -250,7 +254,7 @@ Ensure variety across different categories when possible.
# Check cancellation before the analysis LLM call so a cancel that
# arrives during the search loop doesn't have to wait for the
# expensive analysis pass to finish before terminating.
- self.check_termination()
+ self.check_termination(CHECK_CONTEXT_PRE_ANALYSIS)
# Analyze findings - handle both sync and async contexts
try:
diff --git a/src/local_deep_research/advanced_search_system/strategies/source_based_strategy.py b/src/local_deep_research/advanced_search_system/strategies/source_based_strategy.py
index 2b8e37f8c6..01217317f4 100644
--- a/src/local_deep_research/advanced_search_system/strategies/source_based_strategy.py
+++ b/src/local_deep_research/advanced_search_system/strategies/source_based_strategy.py
@@ -17,7 +17,12 @@ from ..findings.repository import FindingsRepository
from ..parallel_search import run_parallel_searches
from ..questions.atomic_fact_question import AtomicFactQuestionGenerator
from ..questions.standard_question import StandardQuestionGenerator
-from .base_strategy import BaseSearchStrategy
+from .base_strategy import (
+ BaseSearchStrategy,
+ CHECK_CONTEXT_ITERATION_START,
+ CHECK_CONTEXT_POST_SEARCH,
+ CHECK_CONTEXT_PRE_SYNTHESIS,
+)
class SourceBasedSearchStrategy(BaseSearchStrategy):
@@ -217,7 +222,7 @@ class SourceBasedSearchStrategy(BaseSearchStrategy):
)
# Run each iteration
for iteration in range(1, iterations_to_run + 1):
- self.check_termination()
+ self.check_termination(CHECK_CONTEXT_ITERATION_START)
iteration_progress_base = 5 + (iteration - 1) * (
70 / iterations_to_run
)
@@ -388,7 +393,7 @@ class SourceBasedSearchStrategy(BaseSearchStrategy):
# multi-question searches). Without this, a cancel that
# arrived during the search would have to wait for the
# next iteration's loop-entry check before stopping.
- self.check_termination()
+ self.check_termination(CHECK_CONTEXT_POST_SEARCH)
iteration_search_dict = {}
iteration_search_results = []
@@ -463,7 +468,7 @@ class SourceBasedSearchStrategy(BaseSearchStrategy):
# Check cancellation before final synthesis so a stop click that
# arrives right after the last iteration completes doesn't have to
# wait for the synthesis LLM call (10-20 s) before terminating.
- self.check_termination()
+ self.check_termination(CHECK_CONTEXT_PRE_SYNTHESIS)
# SYNTHESIS PHASE — run after all iterations complete.
# The citation handler receives final_filtered_results and produces
diff --git a/src/local_deep_research/advanced_search_system/strategies/topic_organization_strategy.py b/src/local_deep_research/advanced_search_system/strategies/topic_organization_strategy.py
index 81f2d3fe55..10fa8e1808 100644
--- a/src/local_deep_research/advanced_search_system/strategies/topic_organization_strategy.py
+++ b/src/local_deep_research/advanced_search_system/strategies/topic_organization_strategy.py
@@ -4,7 +4,11 @@ from typing import Dict, List, Any, Optional
from loguru import logger
-from .base_strategy import BaseSearchStrategy
+from .base_strategy import (
+ BaseSearchStrategy,
+ CHECK_CONTEXT_ENTRY,
+ CHECK_CONTEXT_REFINEMENT_LOOP,
+)
from .source_based_strategy import SourceBasedSearchStrategy
from .focused_iteration_strategy import FocusedIterationStrategy
from ..findings.topic import Topic, TopicGraph
@@ -938,7 +942,7 @@ Otherwise, respond with only the follow-up question, nothing else.
# strategy. The delegate has its own checks, but the LLM topic-
# extraction call below this point can also take 10-30 s, so we
# want to give the user a chance to bail before we pay that cost.
- self.check_termination()
+ self.check_termination(CHECK_CONTEXT_ENTRY)
strategy_name = (
"focused iteration"
@@ -1131,7 +1135,7 @@ Otherwise, respond with only the follow-up question, nothing else.
# Check cancellation at the top of each refinement iteration
# so a cancel that arrives mid-refinement halts cleanly before
# another LLM refinement-question generation call.
- self.check_termination()
+ self.check_termination(CHECK_CONTEXT_REFINEMENT_LOOP)
refinement_question = self._generate_refinement_question(
relevant_topics, query
diff --git a/tests/advanced_search_system/strategies/test_focused_iteration_high_value.py b/tests/advanced_search_system/strategies/test_focused_iteration_high_value.py
index e8fcfd71fd..749881705e 100644
--- a/tests/advanced_search_system/strategies/test_focused_iteration_high_value.py
+++ b/tests/advanced_search_system/strategies/test_focused_iteration_high_value.py
@@ -8,6 +8,11 @@ LLM or network calls.
from unittest.mock import MagicMock, patch
+from local_deep_research.advanced_search_system.strategies.base_strategy import (
+ CHECK_CONTEXT_ITERATION_START,
+ CHECK_CONTEXT_PRE_SYNTHESIS,
+)
+
import pytest
# ---------------------------------------------------------------------------
@@ -277,16 +282,40 @@ class TestCancellationDuringIterations:
return _make_strategy(), callback, call_counter
+ @staticmethod
+ def _cancel_on_context(target_context, occurrence=1):
+ """Cancel at the Nth firing of one named check_termination site.
+
+ Targets the ``context`` slug the call site passes, so the test
+ stays pinned to the intended check even when progress emits or
+ other checks are added earlier in the flow.
+ """
+ from local_deep_research.exceptions import (
+ ResearchTerminatedException,
+ )
+
+ fired = {"n": 0}
+
+ def callback(message, progress_percent, metadata):
+ if (
+ metadata.get("phase") == "termination_check"
+ and metadata.get("context") == target_context
+ ):
+ fired["n"] += 1
+ if fired["n"] == occurrence:
+ raise ResearchTerminatedException("cancelled")
+
+ return callback, fired
+
def test_cancel_during_first_iteration_stops_loop(self):
- """When the cancel fires on the first termination_check, no
+ """When the cancel fires on iteration 1's loop-entry check, no
iteration of question generation should run."""
from local_deep_research.exceptions import (
ResearchTerminatedException,
)
- strategy, callback, counter = self._make_strategy_with_callback(
- cancel_on_call=1
- )
+ strategy = _make_strategy()
+ callback, fired = self._cancel_on_context(CHECK_CONTEXT_ITERATION_START)
strategy.set_progress_callback(callback)
# Spy on question generation — if cancellation works, this MUST
@@ -304,6 +333,7 @@ class TestCancellationDuringIterations:
with pytest.raises(ResearchTerminatedException):
strategy.analyze_topic("test query")
+ assert fired["n"] == 1
assert gen_mock.call_count == 0, (
"check_termination() should fire BEFORE the first question-"
"generation call so a cancel during the early 'init' "
@@ -346,21 +376,10 @@ class TestCancellationDuringIterations:
"""A cancel that fires after iteration 1 completes must stop the
loop before iteration 2 starts its question generation.
- Walk-through of the callback sequence with the fix in place
- (default max_iterations=8, use_browsecomp_optimization=True):
-
- iter 1:
- cb 1: termination_check (loop entry check)
- cb 2: question_generation (progress milestone)
- (LLM question-generation runs)
- (explorer.explore() runs, no callbacks)
- cb 3: termination_check (after-explore check)
- iter 2:
- cb 4: termination_check (loop entry check — CANCEL HERE)
-
- So cancelling on the 4th callback (start of iteration 2's loop
- body) is the correct expression of "cancel detected between
- iterations". Before the fix, ``analyze_topic`` had no
+ Cancelling at the SECOND ``iteration_start`` check (the loop-entry
+ check of iteration 2) is the exact expression of "cancel detected
+ between iterations": iteration 1 has fully completed, iteration 2
+ has done no work yet. Before the fix, ``analyze_topic`` had no
``check_termination()`` call in the loop at all, so the test
would NOT raise — proving the bug.
"""
@@ -369,15 +388,9 @@ class TestCancellationDuringIterations:
)
strategy = _make_strategy()
- call_counter = {"n": 0}
-
- def callback(message, progress_percent, metadata):
- call_counter["n"] += 1
- # Cancel at the start of iteration 2's loop body (cb 4),
- # i.e. after iteration 1 has fully completed.
- if call_counter["n"] == 4:
- raise ResearchTerminatedException("cancelled")
-
+ callback, fired = self._cancel_on_context(
+ "iteration_start", occurrence=2
+ )
strategy.set_progress_callback(callback)
gen_call_count = {"n": 0}
@@ -422,6 +435,7 @@ class TestCancellationDuringIterations:
# NOT have. Before the fix there was no check_termination() in
# the loop at all, so this would have been 8 (default
# max_iterations).
+ assert fired["n"] == 2
assert gen_call_count["n"] == 1, (
"Cancel between iteration 1 and iteration 2 must stop the "
"loop before iteration 2's question-generation call. Got "
@@ -438,31 +452,31 @@ class TestCancellationDuringIterations:
strategy = _make_strategy(max_iterations=1)
- # The pre-synthesis check_termination() is the LAST
- # termination_check callback before _update_progress("Synthesizing…").
- # Cancel on that termination_check so we assert the synthesis LLM
- # call (analyze_followup) is never reached.
- call_counter = {"n": 0, "saw_termination_before_synthesis": False}
-
- def callback(message, progress_percent, metadata):
- call_counter["n"] += 1
- # The pre-synthesis check fires with phase=termination_check
- # and message="Checking termination status" *before* the
- # "Synthesizing …" milestone.
- if metadata.get(
- "phase"
- ) == "termination_check" and "Synthesizing" not in (message or ""):
- call_counter["saw_termination_before_synthesis"] = True
- raise ResearchTerminatedException("cancelled")
-
+ # Cancel at the pre-synthesis check so we assert the synthesis
+ # LLM call (analyze_followup) is never reached. explore must be
+ # mocked: analyze_topic wraps the loop in ``except Exception``,
+ # so an unmocked explore blowing up on the MagicMock search
+ # would error-return before ever reaching the pre-synthesis
+ # check (the old ordinal test cancelled at the loop-entry check
+ # and never noticed).
+ callback, fired = self._cancel_on_context(CHECK_CONTEXT_PRE_SYNTHESIS)
strategy.set_progress_callback(callback)
+ class _FakeSearchProgress:
+ found_candidates = []
+ entity_coverage = {}
+
with (
patch.object(
strategy.question_generator,
"generate_questions",
return_value=["Q1"],
),
+ patch.object(
+ strategy.explorer,
+ "explore",
+ return_value=([], _FakeSearchProgress()),
+ ),
patch.object(
strategy.citation_handler,
"analyze_followup",
@@ -472,8 +486,8 @@ class TestCancellationDuringIterations:
with pytest.raises(ResearchTerminatedException):
strategy.analyze_topic("test query")
- assert call_counter["saw_termination_before_synthesis"] is True, (
- "Expected a termination_check callback before synthesis"
+ assert fired["n"] == 1, (
+ "Expected the pre_synthesis termination check to fire"
)
assert synth_mock.call_count == 0, (
"Pre-synthesis check_termination() must abort before the "
diff --git a/tests/advanced_search_system/strategies/test_strategy_cancellation_regression.py b/tests/advanced_search_system/strategies/test_strategy_cancellation_regression.py
index fbc5e2f728..7dc2cc6271 100644
--- a/tests/advanced_search_system/strategies/test_strategy_cancellation_regression.py
+++ b/tests/advanced_search_system/strategies/test_strategy_cancellation_regression.py
@@ -1,20 +1,46 @@
-"""Behavioural regression tests for the cancellation-lag fix ported from PR #4872 (#4871)."""
+"""Behavioural regression tests for the cancellation-lag fix ported from PR #4872 (#4871).
+
+Each test cancels at one specific ``check_termination`` call site by
+targeting the ``context`` slug that call passes (e.g. ``"pre_synthesis"``),
+so the tests stay valid when unrelated progress emits or additional checks
+are added earlier in a strategy's flow.
+"""
from unittest.mock import MagicMock, patch
+
+from local_deep_research.advanced_search_system.strategies.base_strategy import (
+ CHECK_CONTEXT_ENTRY,
+ CHECK_CONTEXT_FALLBACK_SYNTHESIS,
+ CHECK_CONTEXT_ITERATION_START,
+ CHECK_CONTEXT_POST_SEARCH,
+ CHECK_CONTEXT_PRE_ANALYSIS,
+ CHECK_CONTEXT_PRE_SYNTHESIS,
+ CHECK_CONTEXT_REFINEMENT_LOOP,
+)
import pytest
-def _cancel_on_nth_callback(cancel_on_call):
+def _cancel_on_context(target_context):
+ """Build a progress callback that cancels at one named check site.
+
+ Only a ``termination_check`` callback whose ``context`` matches
+ ``target_context`` raises; every other progress emission is ignored.
+ ``fired["n"]`` counts how often the targeted check actually fired so
+ tests can assert the site was reached (and not, say, skipped entirely).
+ """
from local_deep_research.exceptions import ResearchTerminatedException
- counter = {"n": 0}
+ fired = {"n": 0}
def callback(message, progress_percent, metadata):
- counter["n"] += 1
- if counter["n"] == cancel_on_call:
+ if (
+ metadata.get("phase") == "termination_check"
+ and metadata.get("context") == target_context
+ ):
+ fired["n"] += 1
raise ResearchTerminatedException("cancelled")
- return callback, counter
+ return callback, fired
def _make_source_based_strategy():
@@ -32,7 +58,7 @@ class TestSourceBasedCancellation:
from local_deep_research.exceptions import ResearchTerminatedException
strategy = _make_source_based_strategy()
- callback, _c = _cancel_on_nth_callback(cancel_on_call=1)
+ callback, fired = _cancel_on_context(CHECK_CONTEXT_ITERATION_START)
strategy.set_progress_callback(callback)
gen_mock = MagicMock(return_value=["Q1"])
with patch.object(
@@ -45,24 +71,16 @@ class TestSourceBasedCancellation:
):
with pytest.raises(ResearchTerminatedException):
strategy.analyze_topic("test query")
+ assert fired["n"] == 1
assert gen_mock.call_count == 0
def test_cancel_after_parallel_search_stops_next_iteration(self):
from local_deep_research.exceptions import ResearchTerminatedException
strategy = _make_source_based_strategy()
- # Cancel on the FIRST iteration loop entry; this is exactly the new
- # check_termination inserted after the parallel search, before the
- # next iteration starts.
- term_counter = {"n": 0}
-
- def callback(message, progress_percent, metadata):
- if metadata.get("phase") == "termination_check":
- term_counter["n"] += 1
- if term_counter["n"] == 2:
- # 2nd termination_check = post-search check on iteration 1
- raise ResearchTerminatedException("cancelled")
-
+ # Cancel at the post-search check of iteration 1 — the check
+ # inserted after run_parallel_searches, before the next iteration.
+ callback, fired = _cancel_on_context(CHECK_CONTEXT_POST_SEARCH)
strategy.set_progress_callback(callback)
gen_calls = {"n": 0}
@@ -91,21 +109,14 @@ class TestSourceBasedCancellation:
strategy.analyze_topic("test query")
# gen_questions WAS called for iteration 1, but cancelled before
# iteration 2 — so it should have been called exactly once, not twice.
+ assert fired["n"] == 1
assert gen_calls["n"] == 1
- assert term_counter["n"] == 2
def test_cancel_before_synthesis_aborts_llm_call(self):
from local_deep_research.exceptions import ResearchTerminatedException
strategy = _make_source_based_strategy()
- call_state = {"saw_pre_synthesis_check": False}
-
- def callback(message, progress_percent, metadata):
- if metadata.get("phase") == "termination_check":
- if message and "Synthesizing" not in str(message):
- call_state["saw_pre_synthesis_check"] = True
- raise ResearchTerminatedException("cancelled")
-
+ callback, fired = _cancel_on_context(CHECK_CONTEXT_PRE_SYNTHESIS)
strategy.set_progress_callback(callback)
strategy.search.run = MagicMock(return_value=[])
synth_mock = MagicMock(
@@ -127,7 +138,7 @@ class TestSourceBasedCancellation:
):
with pytest.raises(ResearchTerminatedException):
strategy.analyze_topic("test query")
- assert call_state["saw_pre_synthesis_check"] is True
+ assert fired["n"] == 1
assert synth_mock.call_count == 0
@@ -145,7 +156,7 @@ class TestNewsStrategyCancellation:
from local_deep_research.exceptions import ResearchTerminatedException
strategy = _make_news_strategy()
- callback, _c = _cancel_on_nth_callback(cancel_on_call=2)
+ callback, fired = _cancel_on_context(CHECK_CONTEXT_PRE_ANALYSIS)
strategy.set_progress_callback(callback)
with patch.object(
strategy.question_generator,
@@ -161,13 +172,14 @@ class TestNewsStrategyCancellation:
strategy.model.invoke = model_invoke
with pytest.raises(ResearchTerminatedException):
strategy.analyze_topic("news query")
+ assert fired["n"] == 1
assert model_invoke.call_count == 0
def test_cancel_before_work_runs_no_search(self):
from local_deep_research.exceptions import ResearchTerminatedException
strategy = _make_news_strategy()
- callback, _c = _cancel_on_nth_callback(cancel_on_call=1)
+ callback, fired = _cancel_on_context(CHECK_CONTEXT_ENTRY)
strategy.set_progress_callback(callback)
gen_mock = MagicMock(return_value=["Q1"])
with patch.object(
@@ -177,6 +189,8 @@ class TestNewsStrategyCancellation:
strategy.search.run = search_mock
with pytest.raises(ResearchTerminatedException):
strategy.analyze_topic("news query")
+ assert fired["n"] == 1
+ assert gen_mock.call_count == 0
assert search_mock.call_count == 0
@@ -196,7 +210,7 @@ class TestTopicOrganizationCancellation:
from local_deep_research.exceptions import ResearchTerminatedException
strategy = _make_topic_org_strategy()
- callback, _c = _cancel_on_nth_callback(cancel_on_call=1)
+ callback, fired = _cancel_on_context(CHECK_CONTEXT_ENTRY)
strategy.set_progress_callback(callback)
delegate_mock = MagicMock(
return_value={
@@ -209,6 +223,7 @@ class TestTopicOrganizationCancellation:
strategy.source_strategy.analyze_topic = delegate_mock
with pytest.raises(ResearchTerminatedException):
strategy.analyze_topic("topic query")
+ assert fired["n"] == 1
assert delegate_mock.call_count == 0
def test_cancel_in_refinement_loop_stops_next_iteration(self):
@@ -222,9 +237,14 @@ class TestTopicOrganizationCancellation:
strategy.iteration_history = []
strategy.topic_graph = MagicMock()
strategy.source_strategy = MagicMock()
+ # The delegate must return at least one source: analyze_topic
+ # early-returns before the refinement loop when all_links_of_system
+ # is empty, and the loop is where the targeted check lives.
strategy.source_strategy.analyze_topic = MagicMock(
return_value={
- "all_links_of_system": [],
+ "all_links_of_system": [
+ {"title": "T", "snippet": "S", "link": "http://x"}
+ ],
"iterations": 0,
"questions_by_iteration": {},
}
@@ -235,7 +255,7 @@ class TestTopicOrganizationCancellation:
refinement_gen_mock = MagicMock(
side_effect=["second question", "third question"]
)
- callback, _c = _cancel_on_nth_callback(cancel_on_call=2)
+ callback, fired = _cancel_on_context(CHECK_CONTEXT_REFINEMENT_LOOP)
strategy.set_progress_callback(callback)
with (
patch.object(
@@ -250,7 +270,10 @@ class TestTopicOrganizationCancellation:
):
with pytest.raises(ResearchTerminatedException):
strategy.analyze_topic("topic query")
- assert refinement_gen_mock.call_count <= 1
+ # Cancelled at the top of the first refinement iteration, before
+ # any refinement-question LLM call.
+ assert fired["n"] == 1
+ assert refinement_gen_mock.call_count == 0
# EnhancedContextualFollowupStrategy
@@ -284,7 +307,7 @@ class TestEnhancedContextualFollowupCancellation:
from local_deep_research.exceptions import ResearchTerminatedException
strategy = _make_followup_strategy()
- callback, _c = _cancel_on_nth_callback(cancel_on_call=1)
+ callback, fired = _cancel_on_context(CHECK_CONTEXT_ENTRY)
strategy.set_progress_callback(callback)
contextualized_query_mock = MagicMock(return_value="rewritten query")
strategy.question_generator.generate_contextualized_query = (
@@ -292,6 +315,7 @@ class TestEnhancedContextualFollowupCancellation:
)
with pytest.raises(ResearchTerminatedException):
strategy.analyze_topic("follow-up query")
+ assert fired["n"] == 1
assert contextualized_query_mock.call_count == 0
assert strategy.delegate_strategy.analyze_topic.call_count == 0
@@ -318,18 +342,7 @@ class TestLangGraphFallbackSynthesisCancellation:
[{"title": "T", "snippet": "S", "link": "http://x"}],
engine_name="web",
)
- # Cancel on the very first termination_check (i.e. the one inserted
- # at the top of _synthesize_from_collector).
- cancel_fired = {"n": False}
-
- def callback(message, progress_percent, metadata):
- if (
- metadata.get("phase") == "termination_check"
- and not cancel_fired["n"]
- ):
- cancel_fired["n"] = True
- raise ResearchTerminatedException("cancelled")
-
+ callback, fired = _cancel_on_context(CHECK_CONTEXT_FALLBACK_SYNTHESIS)
strategy.set_progress_callback(callback)
model_invoke = MagicMock(
return_value=MagicMock(content="synthesized answer")
@@ -337,5 +350,5 @@ class TestLangGraphFallbackSynthesisCancellation:
strategy.model.invoke = model_invoke
with pytest.raises(ResearchTerminatedException):
strategy._synthesize_from_collector("test query")
- assert cancel_fired["n"] is True
+ assert fired["n"] == 1
assert model_invoke.call_count == 0
diff --git a/tests/strategies/test_cancellation_checks.py b/tests/strategies/test_cancellation_checks.py
index 089385195d..0b9561053c 100644
--- a/tests/strategies/test_cancellation_checks.py
+++ b/tests/strategies/test_cancellation_checks.py
@@ -14,6 +14,7 @@ import pytest
from local_deep_research.advanced_search_system.strategies.base_strategy import (
BaseSearchStrategy,
+ CHECK_CONTEXT_PRE_SYNTHESIS,
)
from local_deep_research.exceptions import ResearchTerminatedException
@@ -36,6 +37,29 @@ class TestCheckTerminationMethod:
strategy.progress_callback.assert_called_once()
args = strategy.progress_callback.call_args
assert args[0][2]["phase"] == "termination_check"
+ assert "context" not in args[0][2]
+
+ def test_context_included_in_metadata(self):
+ """A context slug names the call site in the callback metadata.
+
+ Call sites pass e.g. ``check_termination("pre_synthesis")`` so
+ tests can cancel at one specific check instead of counting
+ callback invocations.
+ """
+
+ class ConcreteStrategy(BaseSearchStrategy):
+ def analyze_topic(self, query):
+ pass
+
+ strategy = ConcreteStrategy.__new__(ConcreteStrategy)
+ strategy.progress_callback = MagicMock()
+
+ strategy.check_termination(CHECK_CONTEXT_PRE_SYNTHESIS)
+
+ strategy.progress_callback.assert_called_once()
+ args = strategy.progress_callback.call_args
+ assert args[0][2]["phase"] == "termination_check"
+ assert args[0][2]["context"] == CHECK_CONTEXT_PRE_SYNTHESIS
def test_no_callback_no_error(self):
"""check_termination should not error if no callback set."""
@@ -77,7 +101,7 @@ class TestStrategiesCallCheckTermination:
)
source = inspect.getsource(SourceBasedSearchStrategy.analyze_topic)
- assert "self.check_termination()" in source
+ assert "self.check_termination(" in source
def test_focused_iteration_calls_check(self):
"""FocusedIterationStrategy.analyze_topic must call check_termination().
@@ -95,7 +119,7 @@ class TestStrategiesCallCheckTermination:
)
source = inspect.getsource(FocusedIterationStrategy.analyze_topic)
- assert "self.check_termination()" in source
+ assert "self.check_termination(" in source
def test_news_calls_check(self):
"""NewsStrategy.analyze_topic must call check_termination().
@@ -111,7 +135,7 @@ class TestStrategiesCallCheckTermination:
)
source = inspect.getsource(NewsAggregationStrategy.analyze_topic)
- assert "self.check_termination()" in source
+ assert "self.check_termination(" in source
def test_topic_organization_calls_check(self):
"""TopicOrganizationStrategy.analyze_topic must call check_termination().
@@ -126,7 +150,7 @@ class TestStrategiesCallCheckTermination:
)
source = inspect.getsource(TopicOrganizationStrategy.analyze_topic)
- assert "self.check_termination()" in source
+ assert "self.check_termination(" in source
def test_enhanced_contextual_followup_calls_check(self):
"""EnhancedContextualFollowupStrategy.analyze_topic must call check_termination().
@@ -142,7 +166,7 @@ class TestStrategiesCallCheckTermination:
source = inspect.getsource(
EnhancedContextualFollowUpStrategy.analyze_topic
)
- assert "self.check_termination()" in source
+ assert "self.check_termination(" in source
def test_langgraph_calls_check(self):
"""LangGraphAgentStrategy.analyze_topic must call check_termination().
@@ -157,12 +181,12 @@ class TestStrategiesCallCheckTermination:
)
source = inspect.getsource(LangGraphAgentStrategy.analyze_topic)
- assert "self.check_termination()" in source
+ assert "self.check_termination(" in source
# Also verify the fallback synthesis LLM call path is gated.
synth_source = inspect.getsource(
LangGraphAgentStrategy._synthesize_from_collector
)
- assert "self.check_termination()" in synth_source
+ assert "self.check_termination(" in synth_source
class TestResearchTerminatedException: