~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
feat(citation): source-tagged citations with global counter (#4012)
LearningCircuitf7f427bff76e
diff --git a/changelog.d/4012.feature.md b/changelog.d/4012.feature.mdnew file mode 100644index 0000000000..d7566195f3--- /dev/null+++ b/changelog.d/4012.feature.md@@ -0,0 +1 @@+**New citation format: source-tagged with global numbering.** Reports can now render citations as `[arxiv-1]`, `[openai.com-2]`, `[arxiv-3]` — the source tag identifies what kind of source each citation is (short URLClassifier tag for known academic sources, cleaned domain for generic web URLs, or the collection name for local RAG/library hits, e.g. `[my-papers-4]`), while the number stays the original global counter so labels never collide and inline citations match the bibliography order. Opt in via `report.citation_format → "Source-tagged with global numbering"`; the existing default remains `Numbers with hyperlinks [1]`.diff --git a/src/local_deep_research/defaults/default_settings.json b/src/local_deep_research/defaults/default_settings.jsonindex f3abe78c7e..ce0e162241 100644--- a/src/local_deep_research/defaults/default_settings.json+++ b/src/local_deep_research/defaults/default_settings.json@@ -682,7 +682,7 @@},"report.citation_format": {"category": "report_parameters",- "description": "Citation formatting style for reports. Options include numbered hyperlinks [1], domain-based hyperlinks [arxiv.org], smart domain numbering [arxiv.org-1], and plain numbered references without links.",+ "description": "Citation formatting style for reports. Options include numbered hyperlinks [1], domain-based hyperlinks [arxiv.org], smart domain numbering [arxiv.org-1], source-tagged citations with the global citation number preserved (e.g. [arxiv-1], [openai.com-2], [arxiv-3]), and plain numbered references without links.","editable": true,"max_value": null,"min_value": null,@@ -704,6 +704,10 @@"value": "domain_id_always_hyperlinks","label": "Domain with consistent numbering [arxiv.org-1]"},+ {+ "value": "source_tagged_hyperlinks",+ "label": "Source-tagged with global numbering [arxiv-1, openai.com-2]"+ },{"value": "no_hyperlinks","label": "Numbers without hyperlinks [1]"diff --git a/src/local_deep_research/scheduler/background.py b/src/local_deep_research/scheduler/background.pyindex 5e99680f1e..b61e940797 100644--- a/src/local_deep_research/scheduler/background.py+++ b/src/local_deep_research/scheduler/background.py@@ -1564,6 +1564,7 @@ class BackgroundJobScheduler:"domain_hyperlinks": CitationMode.DOMAIN_HYPERLINKS,"domain_id_hyperlinks": CitationMode.DOMAIN_ID_HYPERLINKS,"domain_id_always_hyperlinks": CitationMode.DOMAIN_ID_ALWAYS_HYPERLINKS,+ "source_tagged_hyperlinks": CitationMode.SOURCE_TAGGED_HYPERLINKS,"no_hyperlinks": CitationMode.NO_HYPERLINKS,}mode = mode_map.get(diff --git a/src/local_deep_research/text_optimization/citation_formatter.py b/src/local_deep_research/text_optimization/citation_formatter.pyindex 89ddaa2b18..8fc8df53e3 100644--- a/src/local_deep_research/text_optimization/citation_formatter.py+++ b/src/local_deep_research/text_optimization/citation_formatter.py@@ -40,6 +40,14 @@ class CitationMode(Enum):DOMAIN_ID_ALWAYS_HYPERLINKS = ("domain_id_always_hyperlinks" # [arxiv.org-1] always with IDs)+ SOURCE_TAGGED_HYPERLINKS = "source_tagged_hyperlinks"+ """Preserve the global citation number and prefix it with a short source+ tag derived from the URL: known academic sources via ``URLClassifier``+ (``arxiv-7``, ``pubmed-3``), domain otherwise (``nytimes.com-9``), and+ ``local-N`` for empty / local URLs. Unlike DOMAIN_ID_* modes the+ suffix is the original citation number, so labels never collide and+ match the bibliography order: ``[1]`` arxiv + ``[2]`` openai + ``[3]``+ arxiv -> ``arxiv-1``, ``openai-2``, ``arxiv-3``."""NO_HYPERLINKS = "no_hyperlinks" # [1] without hyperlinks@@ -142,6 +150,11 @@ class CitationFormatter:# Parse sourcessources = self._parse_sources(sources_content)+ # Optional per-citation collection tags (RAG / library results).+ # Only the source-tagged mode consults this; cheap to compute up+ # front and stashing on ``self`` avoids threading another+ # parameter through every ``_format_*`` method.+ self._collections_for_format = self._parse_collections(sources_content)# Format citations in documentif self.mode == CitationMode.NUMBER_HYPERLINKS:@@ -160,6 +173,10 @@ class CitationFormatter:formatted_content = self._format_domain_id_always_hyperlinks(document_content, sources)+ elif self.mode == CitationMode.SOURCE_TAGGED_HYPERLINKS:+ formatted_content = self._format_source_tagged_hyperlinks(+ document_content, sources+ )else:formatted_content = document_content@@ -385,6 +402,170 @@ class CitationFormatter:self._create_source_word_replacer(formatter), content)+ # Sources section may carry a "Collection: <name>" line for RAG /+ # library hits (emitted by ``utilities/search_utilities.format_links_to_markdown``).+ # The line sits between this ``[N]`` entry's ``URL:`` line and the+ # next ``[N+1]`` entry. We anchor the match on a non-greedy span up+ # to the next citation header (or end of string) to scope correctly.+ _collection_line_pattern = re.compile(+ r"^\[(\d+(?:,\s*\d+)*)\][^\n]*\n" # the [N] header line+ r"(?:[^\n\[]*\n)*?" # any non-[ lines (typically URL: ...)+ r"\s*Collection:\s*(.+?)\s*$",+ re.MULTILINE,+ )++ def _parse_collections(self, sources_content: str) -> Dict[str, str]:+ """Extract ``{citation_num: collection_name}`` from a sources+ block. Returns an empty dict when no ``Collection:`` lines exist+ — the absence of collection info is the common case (web URLs)+ and must never raise."""+ collections: Dict[str, str] = {}+ for match in self._collection_line_pattern.finditer(sources_content):+ citation_nums_str = match.group(1)+ collection = match.group(2).strip()+ if not collection:+ continue+ for num in (n.strip() for n in citation_nums_str.split(",")):+ collections[num] = collection+ return collections++ def _format_source_tagged_hyperlinks(+ self, content: str, sources: Dict[str, Tuple[str, str]]+ ) -> str:+ """Replace ``[N]`` with ``[[source-N]](url)``.++ ``source`` resolves to (in order): the RAG ``Collection:``+ tag for library hits, the short URLClassifier tag for known+ academic sources (``arxiv``, ``pubmed``, ...), the cleaned+ domain otherwise, or ``local`` for empty/file URLs. ``N`` is+ the original global citation number — labels never collide and+ the suffix always matches the bibliography ordering.+ """+ # Filter sources that have URLs, plus carry local entries through+ # with an empty URL (they get the ``local-N`` label and no link).+ usable_sources = {+ num: (title, url) for num, (title, url) in sources.items()+ }++ # Find the sources block again to re-parse the optional+ # ``Collection:`` lines. The caller already split this off in+ # ``format_document`` but didn't pass it through; reparse from+ # the original content via the existing helper to stay local.+ # (Cheap — single regex scan over the sources block.)+ collections = self._collections_for_format++ def format_link(citation_num, data):+ _, url = data+ label = self._extract_source_label(+ url, collection=collections.get(citation_num)+ )+ tag = f"{label}-{citation_num}"+ # Only emit a hyperlink for http(s) URLs — local/file URLs are+ # rendered as plain bracketed tags so the markdown stays clean+ # and viewers don't try to navigate to a server-local path.+ return (+ f"[[{tag}]]({url})"+ if self._is_linkable_url(url)+ else f"[{tag}]"+ )++ # Handle comma-separated citations like [1, 2, 3]+ content = self._replace_comma_citations(+ content, usable_sources, format_link+ )++ formatter = self._create_citation_formatter(usable_sources, format_link)++ # Handle individual citations+ def replace_citation(match):+ return (+ formatter(match.group(1))+ if match.group(1) in usable_sources+ else match.group(0)+ )++ content = self.citation_pattern.sub(replace_citation, content)++ # Also handle "Source X" patterns+ return self.source_word_pattern.sub(+ self._create_source_word_replacer(formatter), content+ )++ @staticmethod+ def _slugify_collection(name: str) -> str:+ """Make a user-set collection name safe for inline citations.++ Collection names are free-form strings (``"My Papers"``,+ ``"team/finance"``). Citations need a compact token that won't+ break markdown — strip whitespace, lowercase, replace runs of+ non-alphanumeric chars with a single hyphen, trim leading and+ trailing hyphens, and fall back to ``"local"`` if the result is+ empty. ``-N`` is appended downstream so we strip trailing+ hyphens to keep the join clean.+ """+ slug = re.sub(r"[^a-z0-9]+", "-", name.strip().lower()).strip("-")+ return slug or "local"++ @staticmethod+ def _is_linkable_url(url: str) -> bool:+ """Return True iff ``url`` is a http(s) URL safe to wrap in a+ markdown hyperlink. Empty strings and file:// / local: schemes+ are not linkable."""+ if not url:+ return False+ try:+ scheme = (urlparse(url).scheme or "").lower()+ except (ValueError, AttributeError):+ return False+ return scheme in ("http", "https")++ def _extract_source_label(+ self, url: str, collection: str | None = None+ ) -> str:+ """Return a short source tag for ``url``.++ Resolution order:+ 1. ``collection`` (when supplied) wins outright — RAG / library+ hits surface their collection name as the citation tag+ (``mypapers``, ``personal-notes``, ...). The renderer in+ ``utilities/search_utilities.format_links_to_markdown``+ emits a ``Collection:`` line per source for library results,+ which the formatter parses back into this argument.+ 2. Empty URL or non-http(s) scheme (``file://``, ``local:``, ...) →+ ``"local"``. Uniform fallback when no collection name is+ available.+ 3. ``URLClassifier`` matches a known academic source → use the+ enum value (``arxiv``, ``pubmed``, ``pmc``, ``biorxiv``,+ ``medrxiv``, ``semantic_scholar``, ``doi``).+ 4. Otherwise → fall back to ``_extract_domain`` (e.g.+ ``arxiv.org``, ``nytimes.com``).+ """+ if collection:+ return self._slugify_collection(collection)+ if not url:+ return "local"+ try:+ parsed = urlparse(url)+ except (ValueError, AttributeError):+ return "local"+ scheme = (parsed.scheme or "").lower()+ if scheme not in ("http", "https"):+ return "local"++ # Lazy import to keep the formatter usable when the content_fetcher+ # package isn't importable (e.g. minimal test setups).+ try:+ from ..content_fetcher.url_classifier import URLClassifier, URLType+ except ImportError:+ return self._extract_domain(url)++ url_type = URLClassifier.classify(url)+ # Generic HTML/PDF/INVALID → fall back to domain. Everything else+ # is a known academic source whose enum value is the short tag.+ if url_type in (URLType.HTML, URLType.PDF, URLType.INVALID):+ return self._extract_domain(url)+ return url_type.value+def _extract_domain(self, url: str) -> str:"""Extract domain name from URL."""try:diff --git a/src/local_deep_research/utilities/search_utilities.py b/src/local_deep_research/utilities/search_utilities.pyindex 85ba6443f9..eb734274e4 100644--- a/src/local_deep_research/utilities/search_utilities.py+++ b/src/local_deep_research/utilities/search_utilities.py@@ -224,6 +224,11 @@ def format_links_to_markdown(all_links: List[Dict]) -> str:url_to_indices: dict[str, list] = {}canon_to_title: dict[str, str] = {}canon_to_quality: dict[str, int] = {}+ # Track the RAG/library collection name per canonical URL so the+ # citation formatter's source-tagged mode can surface it as the+ # citation tag (e.g. `[mypapers-7]`) instead of falling back to+ # the generic `local` label.+ canon_to_collection: dict[str, str] = {}for link in all_links:raw = link.get("url") or link.get("link") or ""canon = canonical_url_key(raw)@@ -234,6 +239,12 @@ def format_links_to_markdown(all_links: List[Dict]) -> str:# Track journal quality per canonical URL (first non-None wins)if canon not in canon_to_quality and link.get("journal_quality"):canon_to_quality[canon] = link["journal_quality"]+ # First non-empty collection name wins (mirrors title/quality).+ if canon not in canon_to_collection:+ metadata = link.get("metadata") or {}+ collection = metadata.get("collection_name")+ if collection:+ canon_to_collection[canon] = str(collection)# Emit each unique source once, in first-seen order.seen: set[str] = set()@@ -246,10 +257,17 @@ def format_links_to_markdown(all_links: List[Dict]) -> str:indices = sorted(set(url_to_indices[canon]))indices_str = f"[{', '.join(map(str, indices))}]"quality_tag = _format_quality_tag(canon_to_quality.get(canon))+ collection_line = (+ f" Collection: {canon_to_collection[canon]}\n"+ if canon in canon_to_collection+ else ""+ )parts.append(f"{indices_str} {title}{quality_tag} "f"(source nr: {', '.join(map(str, indices))})\n"- f" URL: {canon}\n\n"+ f" URL: {canon}\n"+ f"{collection_line}"+ f"\n")seen.add(canon)diff --git a/src/local_deep_research/web/services/research_service.py b/src/local_deep_research/web/services/research_service.pyindex 3da53b6fc2..479d49a414 100644--- a/src/local_deep_research/web/services/research_service.py+++ b/src/local_deep_research/web/services/research_service.py@@ -74,6 +74,7 @@ def get_citation_formatter():"domain_hyperlinks": CitationMode.DOMAIN_HYPERLINKS,"domain_id_hyperlinks": CitationMode.DOMAIN_ID_HYPERLINKS,"domain_id_always_hyperlinks": CitationMode.DOMAIN_ID_ALWAYS_HYPERLINKS,+ "source_tagged_hyperlinks": CitationMode.SOURCE_TAGGED_HYPERLINKS,"no_hyperlinks": CitationMode.NO_HYPERLINKS,}mode = mode_map.get(citation_format, CitationMode.NUMBER_HYPERLINKS)diff --git a/tests/settings/golden_master_settings.json b/tests/settings/golden_master_settings.jsonindex 337293097b..b05aacf936 100644--- a/tests/settings/golden_master_settings.json+++ b/tests/settings/golden_master_settings.json@@ -1833,7 +1833,7 @@},"report.citation_format": {"category": "report_parameters",- "description": "Citation formatting style for reports. Options include numbered hyperlinks [1], domain-based hyperlinks [arxiv.org], smart domain numbering [arxiv.org-1], and plain numbered references without links.",+ "description": "Citation formatting style for reports. Options include numbered hyperlinks [1], domain-based hyperlinks [arxiv.org], smart domain numbering [arxiv.org-1], source-tagged citations with the global citation number preserved (e.g. [arxiv-1], [openai.com-2], [arxiv-3]), and plain numbered references without links.","editable": true,"max_value": null,"min_value": null,@@ -1855,6 +1855,10 @@"label": "Domain with consistent numbering [arxiv.org-1]","value": "domain_id_always_hyperlinks"},+ {+ "label": "Source-tagged with global numbering [arxiv-1, openai.com-2]",+ "value": "source_tagged_hyperlinks"+ },{"label": "Numbers without hyperlinks [1]","value": "no_hyperlinks"diff --git a/tests/text_optimization/test_citation_formatter.py b/tests/text_optimization/test_citation_formatter.pyindex be4ddcf911..418563847c 100644--- a/tests/text_optimization/test_citation_formatter.py+++ b/tests/text_optimization/test_citation_formatter.py@@ -489,6 +489,197 @@ A Nature article [5] and OpenAI research [6].)assert "[[openai.com-1]](https://openai.com/research/gpt4)" in result+ def test_source_tagged_hyperlinks_preserves_global_counter(self):+ """SOURCE_TAGGED_HYPERLINKS keeps the original citation number as+ the suffix, prefixed with the source tag. Two arxiv citations and+ one openai.com citation become [arxiv-1], [openai.com-2],+ [arxiv-3] — not the per-domain renumbering of DOMAIN_ID_*."""+ content = """# Report++Finding A [1]. Finding B [2]. Finding C [3]. Combined [1, 2, 3].++## Sources++[1] First ArXiv Paper+ URL: https://arxiv.org/abs/2024.1111++[2] OpenAI Research+ URL: https://openai.com/research/gpt4++[3] Second ArXiv Paper+ URL: https://arxiv.org/abs/2024.2222+"""+ formatter = CitationFormatter(CitationMode.SOURCE_TAGGED_HYPERLINKS)+ result = formatter.format_document(content)++ # URLClassifier maps arxiv.org URLs to URLType.ARXIV → "arxiv".+ assert "[[arxiv-1]](https://arxiv.org/abs/2024.1111)" in result+ # openai.com is generic HTML → falls back to domain.+ assert "[[openai.com-2]](https://openai.com/research/gpt4)" in result+ # Second arxiv keeps the GLOBAL number 3, not a per-domain "2".+ assert "[[arxiv-3]](https://arxiv.org/abs/2024.2222)" in result+ # Comma-separated citations expand into individual tagged links.+ assert (+ "[[arxiv-1]](https://arxiv.org/abs/2024.1111)"+ "[[openai.com-2]](https://openai.com/research/gpt4)"+ "[[arxiv-3]](https://arxiv.org/abs/2024.2222)"+ ) in result++ def test_source_tagged_hyperlinks_known_academic_sources(self):+ """URLClassifier-recognized academic sources use the short enum+ tag (arxiv, pubmed, semantic_scholar, biorxiv, ...), not the raw+ domain."""+ content = """# Report++Cite [1] and [2] and [3] and [4].++## Sources++[1] ArXiv Paper+ URL: https://arxiv.org/abs/2024.1234++[2] PubMed Paper+ URL: https://pubmed.ncbi.nlm.nih.gov/12345678/++[3] Semantic Scholar+ URL: https://www.semanticscholar.org/paper/Some-Paper/abc123++[4] bioRxiv Preprint+ URL: https://www.biorxiv.org/content/10.1101/2024.01.01.000001v1+"""+ formatter = CitationFormatter(CitationMode.SOURCE_TAGGED_HYPERLINKS)+ result = formatter.format_document(content)+ assert "[[arxiv-1]]" in result+ assert "[[pubmed-2]]" in result+ assert "[[semantic_scholar-3]]" in result+ assert "[[biorxiv-4]]" in result++ def test_source_tagged_hyperlinks_uses_collection_name(self):+ """When the sources block carries a ``Collection:`` line for a+ library/RAG hit, the collection name (slugified) is used as the+ citation tag instead of the URL-derived ``local`` fallback."""+ content = """# Report++Web cite [1]. Library cite [2]. Another web [3]. Another library [4].++## Sources++[1] ArXiv Paper (source nr: 1)+ URL: https://arxiv.org/abs/2024.1111++[2] Local Doc (source nr: 2)+ URL: /library/document/abc123+ Collection: My Papers++[3] OpenAI Research (source nr: 3)+ URL: https://openai.com/research/gpt4++[4] Another local (source nr: 4)+ URL: /library/document/def456+ Collection: team/finance+"""+ formatter = CitationFormatter(CitationMode.SOURCE_TAGGED_HYPERLINKS)+ result = formatter.format_document(content)++ # Web citations are unaffected — still URL-derived tags.+ assert "[[arxiv-1]](https://arxiv.org/abs/2024.1111)" in result+ assert "[[openai.com-3]](https://openai.com/research/gpt4)" in result+ # Library citations adopt the slugified collection name + global N.+ # ``My Papers`` → ``my-papers``, ``team/finance`` → ``team-finance``.+ # Local URLs render without a hyperlink (no http(s) scheme).+ assert "[my-papers-2]" in result+ assert "[[my-papers-2]]" not in result+ assert "[team-finance-4]" in result+ assert "[[team-finance-4]]" not in result++ def test_source_tagged_hyperlinks_collection_slugify_edge_cases(self):+ """Collection names with whitespace, slashes, unicode, or empty+ slugs degrade safely. The slugifier lowercases, replaces runs of+ non-alphanumerics with single hyphens, trims edge hyphens, and+ falls back to ``local`` when the result is empty."""+ from local_deep_research.text_optimization.citation_formatter import (+ CitationFormatter as CF,+ )++ assert CF._slugify_collection("My Papers") == "my-papers"+ assert CF._slugify_collection(" trim me ") == "trim-me"+ assert CF._slugify_collection("team/finance") == "team-finance"+ assert CF._slugify_collection("ALLCAPS") == "allcaps"+ assert CF._slugify_collection("a/b/c") == "a-b-c"+ assert CF._slugify_collection("---") == "local"+ assert CF._slugify_collection("") == "local"+ # Unicode that's not [a-z0-9] collapses to hyphens too. The+ # behaviour is "ASCII-safe slug for inline use" — round-tripping+ # the original name is out of scope.+ assert CF._slugify_collection("résumé") == "r-sum"++ def test_source_tagged_hyperlinks_missing_collection_falls_back(self):+ """A library URL **without** a ``Collection:`` line in the+ sources block falls through to the existing ``local`` tag (this+ is what older renderers and unit tests with hand-rolled sources+ produce)."""+ content = """# Report++See [1].++## Sources++[1] Local doc with no collection metadata+ URL: /library/document/abc123+"""+ formatter = CitationFormatter(CitationMode.SOURCE_TAGGED_HYPERLINKS)+ result = formatter.format_document(content)+ # ``/library/document/...`` has no scheme → ``local`` fallback,+ # rendered as a plain bracketed tag (no hyperlink).+ assert "[local-1]" in result+ assert "[[local-1]]" not in result++ def test_source_tagged_hyperlinks_collection_line_isolation(self):+ """A ``Collection:`` line attached to citation [N] must not leak+ into citation [N+1]'s tag. Regex anchoring is the load-bearing+ bit here."""+ content = """# Report++See [1] and [2].++## Sources++[1] Local doc with collection+ URL: /library/document/abc+ Collection: project-alpha++[2] ArXiv paper, NO collection+ URL: https://arxiv.org/abs/2024.0001+"""+ formatter = CitationFormatter(CitationMode.SOURCE_TAGGED_HYPERLINKS)+ result = formatter.format_document(content)+ assert "[project-alpha-1]" in result+ # Citation [2] must NOT pick up citation [1]'s collection.+ assert "[[arxiv-2]](https://arxiv.org/abs/2024.0001)" in result+ assert "[project-alpha-2]" not in result++ def test_source_tagged_hyperlinks_local_url_falls_back(self):+ """Empty / non-http(s) URLs get the ``local`` tag and render+ without a hyperlink."""+ content = """# Report++See [1] and [2].++## Sources++[1] A local doc+ URL: file:///srv/library/mypapers/foo.pdf++[2] Another local doc with no URL at all+"""+ formatter = CitationFormatter(CitationMode.SOURCE_TAGGED_HYPERLINKS)+ result = formatter.format_document(content)+ # file:// → "local", with no hyperlink wrapping.+ assert "[local-1]" in result+ assert "[[local-1]]" not in result # no hyperlink, not bracketed twice+ # No URL → also "local", and no hyperlink.+ assert "[local-2]" in result+def test_unicode_lenticular_bracket_citations(self):"""Test that Unicode lenticular brackets【】are recognized and converted."""content = """# Research Reportdiff --git a/tests/text_optimization/test_citation_formatter_high_value.py b/tests/text_optimization/test_citation_formatter_high_value.pyindex 35efab733f..1ce52724df 100644--- a/tests/text_optimization/test_citation_formatter_high_value.py+++ b/tests/text_optimization/test_citation_formatter_high_value.py@@ -26,10 +26,16 @@ class TestCitationMode:CitationMode.DOMAIN_ID_ALWAYS_HYPERLINKS.value== "domain_id_always_hyperlinks")+ assert (+ CitationMode.SOURCE_TAGGED_HYPERLINKS.value+ == "source_tagged_hyperlinks"+ )assert CitationMode.NO_HYPERLINKS.value == "no_hyperlinks"def test_enum_member_count(self):- assert len(CitationMode) == 5+ # NUMBER_HYPERLINKS, DOMAIN_HYPERLINKS, DOMAIN_ID_HYPERLINKS,+ # DOMAIN_ID_ALWAYS_HYPERLINKS, SOURCE_TAGGED_HYPERLINKS, NO_HYPERLINKS+ assert len(CitationMode) == 6# ---------------------------------------------------------------------------diff --git a/tests/utilities/test_search_utilities_formatting.py b/tests/utilities/test_search_utilities_formatting.pyindex 6503c5e736..f345bb0007 100644--- a/tests/utilities/test_search_utilities_formatting.py+++ b/tests/utilities/test_search_utilities_formatting.py@@ -569,3 +569,88 @@ class TestFormatLinksDedupCanonical:assert "ref=main" in resultassert "ref=dev" in resultassert "[1, 2]" not in result+++class TestFormatLinksToMarkdownCollections:+ """Tests for the optional ``Collection:`` line surfaced for+ RAG / library results so the source-tagged citation mode can read+ the collection name back from the rendered sources block."""++ def test_emits_collection_line_when_metadata_present(self):+ from local_deep_research.utilities.search_utilities import (+ format_links_to_markdown,+ )++ links = [+ {+ "title": "Local Paper",+ "url": "/library/document/abc123",+ "index": "1",+ "metadata": {"collection_name": "My Papers"},+ },+ ]+ result = format_links_to_markdown(links)+ assert "URL: /library/document/abc123" in result+ assert "Collection: My Papers" in result++ def test_no_collection_line_when_metadata_absent(self):+ from local_deep_research.utilities.search_utilities import (+ format_links_to_markdown,+ )++ # Plain web hit, no metadata.+ links = [+ {+ "title": "Web Page",+ "url": "https://example.com/page",+ "index": "1",+ },+ ]+ result = format_links_to_markdown(links)+ assert "URL: https://example.com/page" in result+ assert "Collection:" not in result++ def test_no_collection_line_when_metadata_lacks_collection_name(self):+ """metadata may exist for other reasons (engine_name, score, etc.)+ without carrying a collection name. Don't emit the line then."""+ from local_deep_research.utilities.search_utilities import (+ format_links_to_markdown,+ )++ links = [+ {+ "title": "Web Page",+ "url": "https://example.com/page",+ "index": "1",+ "metadata": {"engine_name": "web", "score": 0.91},+ },+ ]+ result = format_links_to_markdown(links)+ assert "Collection:" not in result++ def test_first_non_empty_collection_wins_per_url(self):+ """Two hits for the same canonical URL — the first source with a+ non-empty collection name sets it; later hits don't overwrite.+ Mirrors how title and journal_quality work."""+ from local_deep_research.utilities.search_utilities import (+ format_links_to_markdown,+ )++ links = [+ {+ "title": "Doc",+ "url": "/library/document/abc",+ "index": "1",+ "metadata": {"collection_name": "first"},+ },+ {+ "title": "Doc",+ "url": "/library/document/abc",+ "index": "2",+ "metadata": {"collection_name": "second"},+ },+ ]+ result = format_links_to_markdown(links)+ # Single entry (URLs deduped), carries the first collection.+ assert "Collection: first" in result+ assert "Collection: second" not in result