feat(llm): per-kind evidence deep links with FR text-fragment highlight

2026-09-03 10:41:15 -04:00
parent 4b3f5afdcb
commit 8454ae4be1
2 changed files with 215 additions and 0 deletions
--- a/src/llm/links.py
+++ b/src/llm/links.py
@@ -0,0 +1,86 @@
+"""Evidence deep links: one (url, label) per retrieved chunk (pure).
+
+- comment → regulations.gov comment page, or the attachment on the
+  downloads CDN with ``#page=N`` for PDFs (page located at index time,
+  see ``llm.pages``).
+- rule    → the FR paragraph anchor ``#p-N`` plus a ``:~:text=``
+  scroll-to-text fragment so the browser highlights the passage;
+  degrades to ``#page-N``, then the document URL.
+- corpus  → the item's own URL (``#page=N`` when it is a PDF).
+
+Labels double as the citation tokens the model is told to emit
+(``[91 FR 43949 ¶4]``, ``[CMS-2026-2377-3438 p.4]``).
+"""
+
+from __future__ import annotations
+
+from bib.frlink import text_fragment
+
+_COMMENT = "https://www.regulations.gov/comment/{cid}"
+_DOWNLOAD = "https://downloads.regulations.gov/{cid}/{name}"
+_TITLE_MAX = 60
+
+
+def _short(title: str) -> str:
+    title = " ".join(title.split())
+    if len(title) <= _TITLE_MAX:
+        return title
+    return title[:_TITLE_MAX].rsplit(" ", 1)[0] + "…"
+
+
+def _comment(md: dict[str, str]) -> tuple[str, str]:
+    cid = md.get("comment_id", "")
+    if not cid:
+        return "", md.get("item_key", "")
+    name, page = md.get("attachment", ""), md.get("page", "")
+    if name:
+        url = _DOWNLOAD.format(cid=cid, name=name)
+        if page and name.lower().endswith(".pdf"):
+            return f"{url}#page={page}", f"{cid} p.{page}"
+        return url, cid
+    return _COMMENT.format(cid=cid), cid
+
+
+def _rule(md: dict[str, str], snippet: str) -> tuple[str, str]:
+    base = md.get("html_url", "") or md.get("url", "")
+    page, p_id, ordinal, vol = (
+        md.get("page", ""),
+        md.get("p_id", ""),
+        md.get("ordinal", ""),
+        md.get("fr_volume", ""),
+    )
+    if p_id and page:
+        url = f"{base}#p-{p_id}"
+        frag = text_fragment(snippet)
+        if frag:
+            url = f"{url}:~:text={frag}"
+        label = f"{vol} FR {page} ¶{ordinal}" if vol and ordinal else f"p-{p_id}"
+        return url, label
+    if page:
+        label = f"{vol} FR {page}" if vol else f"page {page}"
+        return f"{base}#page-{page}", label
+    return base, _short(md.get("title", "")) or md.get("item_key", "")
+
+
+def _corpus(md: dict[str, str]) -> tuple[str, str]:
+    url, page = md.get("url", ""), md.get("page", "")
+    if url and page and url.lower().endswith(".pdf"):
+        url = f"{url}#page={page}"
+    title = _short(md.get("title", ""))
+    year = md.get("year", "") or md.get("date", "")[:4]
+    if title and year:
+        label = f"{title} ({year})"
+    else:
+        label = title or md.get("item_key", "")
+    return url, label
+
+
+def for_source(md: dict[str, str], snippet: str) -> tuple[str, str]:
+    """``(url, label)`` for a chunk's metadata. Never raises; degrades
+    to whatever link the metadata supports."""
+    kind = md.get("kind", "") or ("comment" if md.get("comment_id") else "corpus")
+    if kind == "comment":
+        return _comment(md)
+    if kind == "rule":
+        return _rule(md, snippet)
+    return _corpus(md)
--- a/tests/llm/test_links.py
+++ b/tests/llm/test_links.py
@@ -0,0 +1,129 @@
+"""llm.links — kind-specific evidence deep links (pure)."""
+
+from llm.links import for_source
+
+
+class TestComment:
+    def test_plain_comment_links_to_comment_page(self):
+        url, label = for_source(
+            {"kind": "comment", "comment_id": "CMS-2026-2377-3438"}, "snippet"
+        )
+        assert url == "https://www.regulations.gov/comment/CMS-2026-2377-3438"
+        assert label == "CMS-2026-2377-3438"
+
+    def test_pdf_attachment_chunk_links_to_page(self):
+        url, label = for_source(
+            {
+                "kind": "comment",
+                "comment_id": "CMS-2026-2377-3438",
+                "attachment": "attachment_2.pdf",
+                "page": "4",
+            },
+            "s",
+        )
+        assert url == (
+            "https://downloads.regulations.gov/CMS-2026-2377-3438/attachment_2.pdf#page=4"
+        )
+        assert label == "CMS-2026-2377-3438 p.4"
+
+    def test_non_pdf_attachment_no_page(self):
+        url, label = for_source(
+            {"kind": "comment", "comment_id": "C-1", "attachment": "attachment_1.docx"},
+            "s",
+        )
+        assert url == "https://downloads.regulations.gov/C-1/attachment_1.docx"
+        assert label == "C-1"
+
+    def test_missing_comment_id_falls_back_to_item_key(self):
+        url, label = for_source({"kind": "comment", "item_key": "ABCD1234"}, "s")
+        assert label == "ABCD1234"
+        assert url == ""
+
+
+class TestRule:
+    MD = {
+        "kind": "rule",
+        "html_url": "https://www.federalregister.gov/documents/2026/07/16/2026-14327/x",
+        "p_id": "938",
+        "page": "43949",
+        "ordinal": "4",
+        "fr_volume": "91",
+    }
+
+    def test_paragraph_link_with_highlight(self):
+        url, label = for_source(
+            self.MD,
+            "In the FY 2027 Hospice proposed rule, CMS solicited comment. More.",
+        )
+        assert url == (
+            "https://www.federalregister.gov/documents/2026/07/16/2026-14327/x#p-938"
+            ":~:text=In%20the%20FY%202027%20Hospice%20proposed%20rule%2C%20CMS%20solicited%20comment."
+        )
+        assert label == "91 FR 43949 ¶4"
+
+    def test_no_p_id_degrades_to_page_link(self):
+        md = {**self.MD, "p_id": "", "ordinal": ""}
+        url, label = for_source(md, "s")
+        assert url.endswith("/x#page-43949")
+        assert label == "91 FR 43949"
+
+    def test_no_page_degrades_to_document(self):
+        md = {
+            "kind": "rule",
+            "html_url": "https://fr.test/doc",
+            "title": "CY2027 PFS NPRM",
+        }
+        url, label = for_source(md, "s")
+        assert url == "https://fr.test/doc"
+        assert label == "CY2027 PFS NPRM"
+
+
+class TestCorpus:
+    def test_item_url_and_short_title_with_year(self):
+        url, label = for_source(
+            {
+                "kind": "corpus",
+                "url": "https://pubmed.ncbi.nlm.nih.gov/19922199/",
+                "title": "A consensus on palliative care quality metrics for hospital programs",
+                "year": "2009",
+            },
+            "s",
+        )
+        assert url == "https://pubmed.ncbi.nlm.nih.gov/19922199/"
+        assert (
+            label
+            == "A consensus on palliative care quality metrics for hospital… (2009)"
+        )
+
+    def test_pdf_url_gets_page(self):
+        url, _ = for_source(
+            {
+                "kind": "corpus",
+                "url": "https://x.test/report.pdf",
+                "title": "R",
+                "page": "7",
+            },
+            "s",
+        )
+        assert url == "https://x.test/report.pdf#page=7"
+
+    def test_non_pdf_url_ignores_page(self):
+        url, _ = for_source(
+            {
+                "kind": "corpus",
+                "url": "https://x.test/report",
+                "title": "R",
+                "page": "7",
+            },
+            "s",
+        )
+        assert url == "https://x.test/report"
+
+    def test_untitled_falls_back_to_item_key(self):
+        _, label = for_source({"kind": "corpus", "item_key": "K1", "url": ""}, "s")
+        assert label == "K1"
+
+
+def test_unknown_kind_treated_as_corpus():
+    url, label = for_source({"url": "https://u.test", "title": "T"}, "s")
+    assert (url, label) == ("https://u.test", "T")