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.

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.md
new file mode 100644
index 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.py
index 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 logger
from ...citation_handler import CitationHandler
from ...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.results
if not results:
- return "Research could not be completed within the iteration limit."
+ return NO_SYNTHESIS_MESSAGE
summaries = []
for r in results[:20]:
summaries.append(
@@ -2645,26 +2652,25 @@ class LangGraphAgentStrategy(BaseSearchStrategy):
if (
not all_search_results
and 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_answer
documents: list = []
+ citation_failed = False
# Citation handling — only if we have results
if 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 = True
logger.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 helper
diff --git a/tests/strategies/test_langgraph_agent_strategy.py b/tests/strategies/test_langgraph_agent_strategy.py
index 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 warning
for 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 warning
for 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 w
for 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 w
for 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)