~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(citations): sharpen the missing-inline-citation warnings (#5185)
LearningCircuit94ffdcd278c1
diff --git a/changelog.d/+citation-warning-polish.misc.md b/changelog.d/+citation-warning-polish.misc.mdnew file mode 100644index 0000000000..2761480f58--- /dev/null+++ b/changelog.d/+citation-warning-polish.misc.md@@ -0,0 +1 @@+The missing-inline-citations warnings added for #4969 are now more precise: the iteration-limit failure sentinel no longer triggers the skip warning (an agent failure is not a citation gap), lenticular-bracket citations (`【N】`) count as markers, the zero-marker warning is suppressed when the citation handler itself failed (its own warning already fires, including new ones for non-dict handler results and for dicts missing both the `content` and `response` keys — each naming the returned type or missing keys and the query), and the log wording states facts without referencing internal issue numbers.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 60be444b7b..630f44a445 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@@ -24,7 +24,11 @@ from loguru import loggerfrom ...citation_handler import CitationHandlerfrom ...security.egress import EngineClassification, classify_engine-from ...security import redact_url_for_log, sanitize_error_for_client+from ...security import (+ redact_url_for_log,+ sanitize_error_for_client,+ scrub_error,+)from ...utilities.chunk_anchor import (build_chunk_anchor_url,extract_chunk_index,@@ -67,12 +71,15 @@ SUBAGENT_TIMEOUT_SECONDS = 1800 # 30 minutes per subagent, measured from# each subagent's *actual* start time (not from the drain-loop start, which# used to make queued subagents inherit the wall-clock of everything that# ran before them -- see #5014).-# User-facing sentinel for "the agent produced nothing". _finalize must-# not run the accumulated-sources citation pass over it — that would-# dress the failure up as a cited synthesis instead of surfacing it.+# User-facing sentinels for "the agent produced nothing". _finalize's+# missing-citations warning must stay quiet for both — an agent failure+# is not a citation gap, and tagging it as one misdirects debugging.NO_RESULTS_MESSAGE = ("Research could not produce results. Try a different query.")+NO_SYNTHESIS_MESSAGE = (+ "Research could not be completed within the iteration limit."+)MAX_SUBTOPICS = 5 # preferred batch size; must match the "pass 2-5" contract# in the lead prompt and research_subtopic tool description. A bounded# overflow is queued through the existing worker pool instead of discarded.@@ -2595,7 +2602,7 @@ class LangGraphAgentStrategy(BaseSearchStrategy):results = self.collector.resultsif not results:- return "Research could not be completed within the iteration limit."+ return NO_SYNTHESIS_MESSAGEsummaries = []for r in results[:20]:summaries.append(@@ -2645,26 +2652,25 @@ class LangGraphAgentStrategy(BaseSearchStrategy):if (not all_search_resultsand self.all_links_of_system- and final_answer != NO_RESULTS_MESSAGE+ and final_answer not in (NO_RESULTS_MESSAGE, NO_SYNTHESIS_MESSAGE)):existing_markers = re.findall(- r"\[\d+(?:\s*,\s*\d+)*\]", final_answer or ""+ r"[\[【]\d+(?:\s*,\s*\d+)*[\]】]", final_answer or "")if existing_markers:logger.warning(f"Citation pass skipped: no new sources collected in "f"this call although {len(self.all_links_of_system)} "f"are accumulated; the raw answer already contains "- f"{len(existing_markers)} inline [N] marker(s) and "- f"will be preserved as-is (#4969, query "- f"'{query[:80]}')"+ f"{len(existing_markers)} inline [N]/【N】 marker(s) and "+ f"will be preserved as-is (query '{query[:80]}')")else:logger.warning(f"Citation pass skipped: no new sources collected in "f"this call although {len(self.all_links_of_system)} "f"are accumulated, and the raw answer contains no "- f"inline [N] markers (#4969, query '{query[:80]}')"+ f"inline [N]/【N】 markers (query '{query[:80]}')")# Emit synthesis milestone if it is not an agent failure@@ -2702,6 +2708,7 @@ class LangGraphAgentStrategy(BaseSearchStrategy):synthesized_content = final_answerdocuments: list = []+ citation_failed = False# Citation handling — only if we have resultsif all_search_results:@@ -2712,22 +2719,65 @@ class LangGraphAgentStrategy(BaseSearchStrategy):previous_knowledge=final_answer,nr_of_links=nr_of_links,)- if isinstance(citation_result, dict):+ if isinstance(citation_result, dict) and (+ "content" in citation_result+ or "response" in citation_result+ ):synthesized_content = citation_result.get("content", citation_result.get("response", final_answer))documents = citation_result.get("documents", [])- except Exception:+ elif isinstance(citation_result, dict):+ # An empty dict (or one carrying neither text key)+ # violates the handler contract just like a non-dict+ # return, but would otherwise pass the isinstance+ # check and fall back to the raw answer silently.+ # Only the text falls back: any documents the dict+ # does carry are still returned to the caller, as+ # they were before this branch existed.+ documents = citation_result.get("documents", [])+ citation_failed = True+ logger.warning(+ f"Citation handler returned a dict without a "+ f"'content' or 'response' key; using raw agent "+ f"answer (query '{query[:80]}')"+ )+ else:+ citation_failed = True+ logger.warning(+ f"Citation handler returned a non-dict result "+ f"({type(citation_result).__name__}); using raw "+ f"agent answer (query '{query[:80]}')"+ )+ except Exception as exc:+ citation_failed = Truelogger.warning(- "Citation handler failed, using raw agent answer"+ f"Citation handler failed, using raw agent answer "+ f"(query '{query[:80]}')"+ )+ safe_exc = scrub_error(exc)+ logger.debug(+ f"Citation handler exception details: "+ f"{type(exc).__name__}: {safe_exc}")- if not re.search(r"\[\d", synthesized_content or ""):+ # Suppressed when the handler failed — the raw answer is+ # expected to lack markers then, and blaming "synthesis"+ # would misdirect debugging. The marker pattern must accept+ # every inline form the citation_formatter recognizes, or a+ # fully-cited report trips a false warning: lenticular+ # brackets (LLMs emit 【N】) and comma-grouped markers+ # (`[1, 2]`, which the formatter's comma_citation_pattern+ # parses and the sibling skip-branch check above already+ # matches). A bare `\[\d+\]` misses the grouped-only case.+ if not citation_failed and not re.search(+ r"[\[【]\d+(?:\s*,\s*\d+)*[\]】]", synthesized_content or ""+ ):logger.warning(- f"Synthesis produced no inline [N] citation markers "- f"despite {len(all_search_results)} available sources — "- f"the report body will show no citations for this "- f"query ('{query[:80]}')"+ f"Synthesis produced no inline [N]/【N】 citation markers "+ f"despite {len(all_search_results)} available sources "+ f"— the report body will show no inline citations "+ f"for this query ('{query[:80]}')")# Format sources — delegate to base helperdiff --git a/tests/strategies/test_langgraph_agent_strategy.py b/tests/strategies/test_langgraph_agent_strategy.pyindex c5705a91f5..df15d1c625 100644--- a/tests/strategies/test_langgraph_agent_strategy.py+++ b/tests/strategies/test_langgraph_agent_strategy.py@@ -4435,7 +4435,7 @@ class TestFinalizeCitationLogging:handler.analyze_followup.assert_not_called()assert result["current_knowledge"] == "Uncited raw answer."assert any(- "raw answer contains no inline [N] markers" in warning+ "raw answer contains no inline [N]/【N】 markers" in warningfor warning in self._warnings(mock_logger))@@ -4459,12 +4459,10 @@ class TestFinalizeCitationLogging:)warnings = self._warnings(mock_logger)assert any(- "already contains 2 inline [N] marker(s)" in warning+ "already contains 2 inline [N]/【N】 marker(s)" in warningfor warning in warnings)- assert not any(- "will have no inline [N]" in warning for warning in warnings- )+ assert not any("contains no inline" in warning for warning in warnings)def test_no_results_sentinel_does_not_warn_about_skip(self):"""An agent that produced nothing returns NO_RESULTS_MESSAGE —@@ -4544,7 +4542,7 @@ class TestFinalizeCitationLogging:strategy._finalize("q", "raw", 1, 0, [])assert any(- "no inline [N] citation markers" in w+ "no inline [N]/【N】 citation markers" in wfor w in self._warnings(mock_logger))@@ -4564,7 +4562,7 @@ class TestFinalizeCitationLogging:strategy._finalize("q", "raw", 1, 0, [])assert not any(- "no inline [N] citation markers" in w+ "no inline [N]/【N】 citation markers" in wfor w in self._warnings(mock_logger))@@ -4629,6 +4627,205 @@ class TestFinalizeCitationLogging:in synthesis_updates[0][0])+ def test_no_synthesis_sentinel_does_not_warn_about_skip(self):+ """The iteration-limit sentinel (GraphRecursionError path with an+ empty collector) is an agent failure, not a citation gap — the+ skip warning must stay quiet for it just like NO_RESULTS_MESSAGE."""+ from local_deep_research.advanced_search_system.strategies.langgraph_agent_strategy import (+ NO_SYNTHESIS_MESSAGE,+ )++ handler = MagicMock()+ links = [self._link(1, "https://a.example/x")]+ strategy = self._make_strategy(+ all_links=links, citation_handler=handler+ )++ with patch(self._LOGGER_PATH) as mock_logger:+ result = strategy._finalize("q", NO_SYNTHESIS_MESSAGE, 1, 0, [])++ handler.analyze_followup.assert_not_called()+ assert result["current_knowledge"] == NO_SYNTHESIS_MESSAGE+ assert not any(+ "Citation pass skipped" in w for w in self._warnings(mock_logger)+ )++ def test_lenticular_markers_count_as_citations(self):+ """LLMs sometimes emit lenticular-bracket citations (【1】), which+ the citation formatter accepts — the zero-marker warning must not+ fire on them."""+ handler = MagicMock()+ handler.analyze_followup.return_value = {+ "content": "Per 【1】, the claim holds.",+ "documents": [],+ }+ strategy = self._make_strategy(all_links=[], citation_handler=handler)+ strategy.collector.add_results(+ [{"title": "New", "link": "https://b.example/y", "snippet": "s"}],+ engine_name="web",+ )++ with patch(self._LOGGER_PATH) as mock_logger:+ strategy._finalize("q", "raw", 1, 0, [])++ # Wording-agnostic: a marker-bearing synthesis from a healthy+ # handler must produce no warnings at all, whatever their text.+ assert self._warnings(mock_logger) == []++ def test_comma_grouped_markers_count_as_citations(self):+ """A synthesis that cites only in comma-grouped form (`[1, 2]`)+ is fully cited — the formatter's comma_citation_pattern parses it+ and the sibling skip-branch check matches it. The zero-marker+ warning must not fire on grouped-only markers; this guards the+ regex against a future tightening to a bare `\\[\\d+\\]`, which+ would miss the grouped-only case and warn falsely."""+ handler = MagicMock()+ handler.analyze_followup.return_value = {+ "content": "Based on the combined evidence [1, 2], X holds.",+ "documents": [],+ }+ strategy = self._make_strategy(all_links=[], citation_handler=handler)+ strategy.collector.add_results(+ [{"title": "New", "link": "https://b.example/y", "snippet": "s"}],+ engine_name="web",+ )++ with patch(self._LOGGER_PATH) as mock_logger:+ strategy._finalize("q", "raw", 1, 0, [])++ # Wording-agnostic: a marker-bearing synthesis from a healthy+ # handler must produce no warnings at all, whatever their text.+ assert self._warnings(mock_logger) == []++ def test_handler_exception_suppresses_zero_marker_warning(self):+ """When the citation handler raises, the raw answer is expected+ to lack markers — warn about the failure, not about 'synthesis'+ that never ran."""+ handler = MagicMock()+ handler.analyze_followup.side_effect = RuntimeError("boom")+ strategy = self._make_strategy(all_links=[], citation_handler=handler)+ strategy.collector.add_results(+ [{"title": "New", "link": "https://b.example/y", "snippet": "s"}],+ engine_name="web",+ )++ with patch(self._LOGGER_PATH) as mock_logger:+ result = strategy._finalize("q", "raw uncited", 1, 0, [])++ warnings = self._warnings(mock_logger)+ assert any(+ "Citation handler failed" in w and "(query 'q')" in w+ for w in warnings+ )+ assert not any(+ "no inline [N]/【N】 citation markers" in w for w in warnings+ )+ assert result["current_knowledge"] == "raw uncited"++ def test_handler_non_dict_result_warns_distinctly(self):+ """A handler that violates its contract (non-dict return) must+ produce its own log signal — naming the returned type and the+ query like the surrounding warnings do — not masquerade as+ marker-free synthesis."""+ handler = MagicMock()+ handler.analyze_followup.return_value = "not a dict"+ strategy = self._make_strategy(all_links=[], citation_handler=handler)+ strategy.collector.add_results(+ [{"title": "New", "link": "https://b.example/y", "snippet": "s"}],+ engine_name="web",+ )++ with patch(self._LOGGER_PATH) as mock_logger:+ result = strategy._finalize("q", "raw uncited", 1, 0, [])++ warnings = self._warnings(mock_logger)+ assert any(+ "non-dict result (str)" in w and "(query 'q')" in w+ for w in warnings+ )+ assert not any(+ "no inline [N]/【N】 citation markers" in w for w in warnings+ )+ assert result["current_knowledge"] == "raw uncited"++ def test_handler_empty_dict_result_warns_distinctly(self):+ """An empty dict passes the isinstance check but carries neither+ 'content' nor 'response' — the same contract violation as a+ non-dict return, so it must get its own log signal instead of+ silently falling back to the raw answer."""+ handler = MagicMock()+ handler.analyze_followup.return_value = {}+ strategy = self._make_strategy(all_links=[], citation_handler=handler)+ strategy.collector.add_results(+ [{"title": "New", "link": "https://b.example/y", "snippet": "s"}],+ engine_name="web",+ )++ with patch(self._LOGGER_PATH) as mock_logger:+ result = strategy._finalize("q", "raw uncited", 1, 0, [])++ warnings = self._warnings(mock_logger)+ assert any(+ "dict without a 'content' or 'response' key" in w+ and "(query 'q')" in w+ for w in warnings+ )+ assert not any(+ "no inline [N]/【N】 citation markers" in w for w in warnings+ )+ assert result["current_knowledge"] == "raw uncited"++ def test_handler_keyless_dict_still_returns_documents(self):+ """A dict carrying documents but neither text key gets the+ contract-violation warning, yet its documents must still reach+ the caller — only the text falls back to the raw answer, exactly+ as it did before the keyless-dict branch existed."""+ handler = MagicMock()+ handler.analyze_followup.return_value = {+ "documents": [{"page_content": "doc"}],+ }+ strategy = self._make_strategy(all_links=[], citation_handler=handler)+ strategy.collector.add_results(+ [{"title": "New", "link": "https://b.example/y", "snippet": "s"}],+ engine_name="web",+ )++ with patch(self._LOGGER_PATH) as mock_logger:+ result = strategy._finalize("q", "raw uncited", 1, 0, [])++ assert result["current_knowledge"] == "raw uncited"+ assert result["documents"] == [{"page_content": "doc"}]+ assert any(+ "dict without a 'content' or 'response' key" in w+ for w in self._warnings(mock_logger)+ )++ def test_empty_collector_counts_lenticular_markers(self):+ """The skip-branch marker census must accept the same lenticular+ style the zero-marker check does, or a 【N】-cited raw answer is+ falsely reported as uncited."""+ handler = MagicMock()+ links = [self._link(1, "https://a.example/x")]+ strategy = self._make_strategy(+ all_links=links, citation_handler=handler+ )++ with patch(self._LOGGER_PATH) as mock_logger:+ result = strategy._finalize(+ "q", "Prior evidence 【1】 remains relevant.", 1, 0, []+ )++ handler.analyze_followup.assert_not_called()+ assert result["current_knowledge"] == (+ "Prior evidence 【1】 remains relevant."+ )+ warnings = self._warnings(mock_logger)+ assert any(+ "already contains 1 inline [N]/【N】 marker(s)" in warning+ for warning in warnings+ )+ assert not any("contains no inline" in warning for warning in warnings)+# ---------------------------------------------------------------------------# Round-2 follow-up: collector/bibliography agreement (#5685)