From 481cd3f2e56a3d40ebf022681e5bd94cf339fba2 Mon Sep 17 00:00:00 2001 From: kert Date: Thu, 12 Nov 2026 23:07:03 -0500 Subject: [PATCH] =?UTF-8?q?feat(pfs):=20dossier=20assembly=20=E2=80=94=20c?= =?UTF-8?q?ited=20facts,=20computed=20gaps,=20model=20prose=20behind=20a?= =?UTF-8?q?=20sentence-level=20citation=20check?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit pfs.cite (Cite + builders; rule_label moved from llm.lineage and re-exported), pfs.citecheck (sentence split, number normalization, check_prose; plus grounding_problems: words, codes and CMS-vs-ours attribution of model prose), pfs.dossier (facts with resolved cites from every Task 1-12 table, timeline, stakeholder panels with names from pfs.commenter, stance accuracy beside every count, computed coverage gaps, ledgered model prose with template fallback, pfs.dossier table), llm.search item_keys filter, `stack pfs dossier`. Lineage rows reach the dossier only when a final rule's own plain sentence states them. HOME-VISITS live: 558 facts, 28 timeline events, check passed, prose model:qwen2.5:14b+template (8 of 29 units on templates). --- src/cli/pfs.py | 106 + src/llm/lineage.py | 32 +- src/llm/search.py | 28 +- src/pfs/cite.py | 267 +++ src/pfs/citecheck.py | 278 +++ src/pfs/codetables.py | 6 + src/pfs/dossier.py | 2514 +++++++++++++++++++++++ tests/cli/test_pfs_cli.py | 136 ++ tests/llm/test_lineage.py | 7 + tests/llm/test_search.py | 51 + tests/pfs/conftest.py | 3 + tests/pfs/fixtures/home_visits_fr.jsonl | 33 + tests/pfs/fixtures/home_visits_rvu.csv | 217 ++ tests/pfs/home_visits_fixture.py | 750 +++++++ tests/pfs/test_cite.py | 188 ++ tests/pfs/test_citecheck.py | 214 ++ tests/pfs/test_dossier.py | 1864 +++++++++++++++++ 17 files changed, 6662 insertions(+), 32 deletions(-) create mode 100644 src/pfs/cite.py create mode 100644 src/pfs/citecheck.py create mode 100644 src/pfs/dossier.py create mode 100644 tests/pfs/conftest.py create mode 100644 tests/pfs/fixtures/home_visits_fr.jsonl create mode 100644 tests/pfs/fixtures/home_visits_rvu.csv create mode 100644 tests/pfs/home_visits_fixture.py create mode 100644 tests/pfs/test_cite.py create mode 100644 tests/pfs/test_citecheck.py create mode 100644 tests/pfs/test_dossier.py diff --git a/src/cli/pfs.py b/src/cli/pfs.py index 0a59e1c..28217fb 100644 --- a/src/cli/pfs.py +++ b/src/cli/pfs.py @@ -10,6 +10,7 @@ uv run stack pfs review [--code G0556] uv run stack pfs cpt-ingest --edition 2024 [--edition 2022 …] [--dry-run] uv run stack pfs cpt-ingest --all + uv run stack pfs dossier --family HOME-VISITS [--no-llm] [--limit N] [--write] Writes go through ``duckdb_batch`` (single-writer rule) and republish the read-only replica so the chat and notebooks see them. @@ -65,6 +66,14 @@ from pfs.codetables import ( from pfs.commenters import family_comment_items, identify, regs_for from pfs.cpt_load import ingest as cpt_ingest from pfs.curated import apply_curated, load_curated +from pfs.dossier import ( + build_dossier, + collect_facts, + governance_excerpts, + stakeholder_lines, + write_dossier, +) +from pfs.dossier import timeline as dossier_timeline from pfs.exposure import build as build_exposures from pfs.exposure import control_codes from pfs.extract import extract_codes @@ -2373,3 +2382,100 @@ def _model_of(ask: Any, large: bool) -> str: if ask is not None: return ask.model return _model_name(large=True) if large else _model_name() + + +def _excerpts(store: Any, name: str) -> list[Any]: + """Governance excerpts for a family (embeddings on the llm pool; no + generation).""" + from llm import config as llm_config + from llm.pool import HostPool + + cfg = llm_config.load() + return governance_excerpts(cfg, HostPool.from_config(cfg), store, name) + + +@app.command("dossier") +def dossier_cmd( + family: str = typer.Option("", "--family", help="Curated family key."), + all_families: bool = typer.Option(False, "--all", help="Every curated family."), + no_llm: bool = typer.Option( + False, + "--no-llm", + help="Make no model calls; the finished prose ledger is replayed.", + ), + limit: int = typer.Option(0, "--limit", help="Cap new model calls (0 = all)."), + dry_run: bool = typer.Option( + False, + "--dry-run", + help="Count facts and timeline events; no model calls, no writes.", + ), + write: bool = typer.Option(False, "--write"), +) -> None: + """Assemble a family's dossier (pfs.dossier): every stored fact with its + resolved citation, the computed gaps, and model prose that passes the + sentence-level citation check (template lines otherwise), through a + resumable ledger. Prints the fact count, the gaps, the stakeholder table + and the check result; --write stores it.""" + if all_families: + registry = load_curated() + fams = [registry[k] for k in sorted(registry)] + elif family: + fam = curated_family(normalize_key(family)) + if fam is None: + raise typer.BadParameter(f"unknown curated family {family!r}") + fams = [fam] + else: + raise typer.BadParameter("give --family KEY or --all") + store = _store() + built = [] + for fam in fams: + con = _read() + try: + if dry_run: + facts = collect_facts(con, store, fam) + events = dossier_timeline(facts) + typer.echo( + f"{fam.key}: {len(facts)} facts, {len(events)} timeline events; " + f"model calls a run would make: {len(events) + 1} " + "(each retried once at most)" + ) + continue + d = build_dossier( + con, + store, + fam, + ask=None if no_llm else _asker(), + excerpts=[] if no_llm else _excerpts(store, fam.name), + log=RunLog(ledger_path("prose", fam.key)), + replay_model=_model_name() if no_llm else None, + limit=limit, + ) + finally: + con.close() + kinds = Counter(f.kind for f in d.facts.values()) + typer.echo( + f"{fam.key}: {len(d.facts)} facts (" + + ", ".join(f"{k} {n}" for k, n in sorted(kinds.items())) + + ")" + ) + typer.echo( + "timeline years: " + + ", ".join(str(y) for y in sorted({e.year for e in d.timeline})) + ) + for gap in d.gaps: + typer.echo(f"gap: {gap}") + for line in stakeholder_lines(d): + typer.echo(line) + typer.echo( + f"check: {'passed' if d.check_passed else 'FAILED'}; prose {d.extractor}" + ) + if d.extractor != "template" and d.fallbacks: + typer.echo("template fallback: " + "; ".join(d.fallbacks)) + built.append(d) + if write and built: + with _batch() as bcon: + ensure_tables(bcon) + for d in built: + write_dossier(bcon, d) + typer.echo(f"wrote dossier {d.family}") + _publish() diff --git a/src/llm/lineage.py b/src/llm/lineage.py index 27ba17b..90a2b52 100644 --- a/src/llm/lineage.py +++ b/src/llm/lineage.py @@ -36,6 +36,7 @@ from typing import Any, Sequence from llm.config import LlmConfig from llm.links import as_source +from pfs.cite import rule_label # moved there (dossier task 13); re-exported from pfs.codetables import ( ElementRow, EventRow, @@ -45,7 +46,6 @@ from pfs.codetables import ( read_events, read_guidance, ) -from pfs.descriptors import rule_year_of from pfs.families import detect_codes log = logging.getLogger(__name__) @@ -338,36 +338,6 @@ class LineageEvidence: return out -def rule_label( - title: str, - date_published: str, - p_id: int, - *, - vol: str = "", - page: int = 0, - kind: str = "", -) -> str: - """``"CY2021 PFS final 85 FR 84639 ¶1578"`` when *vol*/*page* are - known (Ruling B13 — ``I2``), else the shorter - ``"CY2021 PFS final ¶1578"`` / ``"CY2027 PFS proposed ¶394"``. - - *kind* is ``proposed`` / ``final`` / ``correction`` / ``rule`` as - decided by ``bib.frlink.rule_kind`` from the rule's own text (the - chat passes it via ``_rule_kind``). Without it the title decides - (``bib.frlink.kind_from_title``) — and a title that says neither - labels the row ``rule``, never ``final``: since CY2018 the CMS - titles carry no proposed/final word, and a proposed rule presented - as final is a false statement of policy. The year comes from - ``rule_year_of``.""" - from bib.frlink import kind_from_title # bib is an optional extra - - year = rule_year_of(title, date_published) - kind = kind or kind_from_title(title) - if vol and page: - return f"CY{year} PFS {kind} {vol} FR {page} ¶{p_id}" - return f"CY{year} PFS {kind} ¶{p_id}" - - # ── The bib Store, opened lazily once PER THREAD (sqlite, cheap) ─────── # # Ruling B14 / C1: bib.Store's sqlite connection is check_same_thread=True diff --git a/src/llm/search.py b/src/llm/search.py index e300dd8..2e655fa 100644 --- a/src/llm/search.py +++ b/src/llm/search.py @@ -88,6 +88,25 @@ def _store_filter(filters: dict[str, str]) -> dict[str, Any]: return out +def _with_item_keys( + store_filter: dict[str, Any], item_keys: Sequence[str] | None +) -> dict[str, Any]: + """*store_filter* restricted to the bib items *item_keys* (``None``: no + restriction) with an ``{"item_key": {"$in": [...]}}`` condition — merged + into a plain field mapping, else joined under ``$and`` (an operator + filter, or one that already pins ``item_key``).""" + if item_keys is None: + return store_filter + cond = {"item_key": {"$in": list(item_keys)}} + if not store_filter: + return cond + if "$and" in store_filter: + return {"$and": [*store_filter["$and"], cond]} + if any(k.startswith("$") for k in store_filter) or "item_key" in store_filter: + return {"$and": [store_filter, cond]} + return {**store_filter, **cond} + + def _year_ok(md: dict[str, Any], year: str) -> bool: if not year: return True @@ -135,6 +154,7 @@ def search( filters: dict[str, str] | None = None, limit: int = 10, offset: int = 0, + item_keys: Sequence[str] | None = None, ) -> list[dict]: """Metadata-filtered similarity search across the selected collection(s), embedding *q* once. @@ -150,13 +170,19 @@ def search( Validation (empty *q*, ``limit``/``collection``/``kind`` ranges) is the API layer's job — this function assumes its inputs are already sane. + + *item_keys* (dossier task 13) restricts the search to those bib items, + pushed into the store filter as ``{"item_key": {"$in": [...]}}``; an + empty set finds nothing (no embedding call). """ from llm.index import vectorstore + if item_keys is not None and not item_keys: + return [] filters = filters or {} year = str(filters.get("year") or "") theme = str(filters.get("theme") or "") - store_filter = _store_filter(filters) + store_filter = _with_item_keys(_store_filter(filters), item_keys) fetch = limit + offset vec = PoolEmbeddings(pool, cfg.embed_model).embed_query(q) diff --git a/src/pfs/cite.py b/src/pfs/cite.py new file mode 100644 index 0000000..71a6840 --- /dev/null +++ b/src/pfs/cite.py @@ -0,0 +1,267 @@ +"""Citations for dossier facts (dossier task 13). + +Every statement on a dossier carries one :class:`Cite`: what kind of source +it is, the label a reader sees, a resolved URL (or ``""`` when none can be +resolved) and, so a fact without a link still says where it comes from, a +human-readable ``locator`` ("87 FR 69608", "CPT Changes 2023 p. 49", +"42 CFR 425.400(c)"). The page never builds a URL itself (R10): every +builder here resolves it once, at assembly time. + +``rule_label`` (the chat's FR paragraph label) lives here so the dossier and +``llm.lineage`` label a rule paragraph the same way; ``llm.lineage`` +re-exports it. +""" + +from __future__ import annotations + +import logging +import re +from dataclasses import dataclass +from typing import Any + +from pfs.descriptors import rule_year_of + +log = logging.getLogger(__name__) + +KINDS: tuple[str, ...] = ( + "fr_para", + "fr_page", + "comment", + "cms_file", + "cpt_book", + "iom", + "cfr", + "mln", + "statute", + "study", + "rvu_file", + "dataset", +) + +#: CMS's page listing the PFS relative value files, every year's release +RVU_FILES_URL = ( + "https://www.cms.gov/medicare/payment/fee-schedules/physician/" + "pfs-relative-value-files" +) +REGS_COMMENT_URL = "https://www.regulations.gov/comment/{id}" +SSA_SECTION_URL = "https://www.ssa.gov/OP_Home/ssact/title18/{section}.htm" + + +@dataclass(frozen=True) +class Cite: + """One citation: ``kind`` (one of :data:`KINDS`), the ``label`` shown, the + resolved ``url`` (``""`` when unresolved), the bib ``item_key`` / + paragraph ``p_id`` / printed ``page`` behind it, and a ``locator`` a + reader can follow without the link.""" + + kind: str + label: str + url: str + item_key: str = "" + p_id: int = 0 + page: int = 0 + locator: str = "" + + +def rule_label( + title: str, + date_published: str, + p_id: int, + *, + vol: str = "", + page: int = 0, + kind: str = "", +) -> str: + """``"CY2021 PFS final 85 FR 84639 ¶1578"`` when *vol*/*page* are + known (Ruling B13 — ``I2``), else the shorter + ``"CY2021 PFS final ¶1578"`` / ``"CY2027 PFS proposed ¶394"``. + + *kind* is ``proposed`` / ``final`` / ``correction`` / ``rule`` as + decided by ``bib.frlink.rule_kind`` from the rule's own text (the + chat passes it via ``_rule_kind``). Without it the title decides + (``bib.frlink.kind_from_title``) — and a title that says neither + labels the row ``rule``, never ``final``: since CY2018 the CMS + titles carry no proposed/final word, and a proposed rule presented + as final is a false statement of policy. The year comes from + ``rule_year_of``.""" + from bib.frlink import kind_from_title # bib is an optional extra + + year = rule_year_of(title, date_published) + kind = kind or kind_from_title(title) + if vol and page: + return f"CY{year} PFS {kind} {vol} FR {page} ¶{p_id}" + return f"CY{year} PFS {kind} ¶{p_id}" + + +# ── Federal Register ──────────────────────────────────────────────── + + +def _rule_meta(store: Any, item_key: str) -> tuple[str, str, str, str] | None: + """``(title, date_published, FR volume, rule kind)`` of a rule item, or + ``None`` when the item is not in the store.""" + from bib.frlink import rule_kind + + con = store._con() # noqa: SLF001 — same pattern as pfs.descriptors + row = con.execute( + "SELECT title, date_published FROM items WHERE key = ?", (item_key,) + ).fetchone() + if row is None: + return None + vol = con.execute( + "SELECT fr_volume FROM fr_anchor_docs WHERE item_key = ?", (item_key,) + ).fetchone() + title, dp = row[0] or "", row[1] or "" + return ( + title, + dp, + str(vol[0]) if vol else "", + rule_kind(store, item_key, title=title), + ) + + +def _resolve(store: Any, ref: str, item_key: str) -> str: + """``bib.frlink.resolve(ref).url``, ``""`` on any failure (logged).""" + from bib import frlink + + try: + return frlink.resolve(ref, store=store, item_key=item_key).url + except Exception as exc: # noqa: BLE001 — an unresolved link is a stated blank + log.warning("FR link unresolved (%s %s): %s", item_key, ref, exc) + return "" + + +def fr_para_cite(store: Any, item_key: str, p_id: int) -> Cite: + """Paragraph *p_id* of the FR rule *item_key*: labelled like the chat + (``rule_label``), the ``#p-N`` jump link, the printed page and the + ``" FR "`` locator. An unknown item or paragraph keeps a + label and a locator, with no URL.""" + meta = _rule_meta(store, item_key) + if meta is None: + where = f"{item_key} ¶{p_id}" + return Cite("fr_para", where, "", item_key, p_id, 0, where) + title, dp, vol, kind = meta + row = ( + store._con() # noqa: SLF001 + .execute( + "SELECT page FROM fr_anchors WHERE item_key = ? AND p_id = ?", + (item_key, p_id), + ) + .fetchone() + ) + if row is None: + return Cite( + "fr_para", + rule_label(title, dp, p_id, kind=kind), + "", + item_key, + p_id, + 0, + f"{item_key} ¶{p_id}", + ) + page = int(row[0] or 0) + return Cite( + "fr_para", + rule_label(title, dp, p_id, vol=vol, page=page, kind=kind), + _resolve(store, f"p-{p_id}", item_key), + item_key, + p_id, + page, + f"{vol} FR {page}" if vol and page else f"{item_key} ¶{p_id}", + ) + + +def fr_page_cite(store: Any, item_key: str, page: int, *, table: str = "") -> Cite: + """Printed page *page* of the FR rule *item_key* (a table cell's page): + ``"CY2008 PFS final 72 FR 66361 Table 14"``.""" + meta = _rule_meta(store, item_key) + if meta is None: + where = f"{item_key} p. {page}" + return Cite("fr_page", where, "", item_key, 0, page, where) + title, dp, vol, kind = meta + cite = f"{vol} FR {page}" + label = f"CY{rule_year_of(title, dp)} PFS {kind} {cite}" + if table: + label += f" {table}" + return Cite( + "fr_page", label, _resolve(store, cite, item_key), item_key, 0, page, cite + ) + + +# ── comments, files, books, datasets ──────────────────────────────── + + +def comment_cite(comment_id: str) -> Cite: + return Cite( + "comment", + f"Comment {comment_id}", + REGS_COMMENT_URL.format(id=comment_id), + locator=comment_id, + ) + + +def rvu_cite(year: int, *, proposed: bool = False) -> Cite: + """The PFS relative value file of *year* (``proposed``: the NPRM's).""" + label = f"PFS CY{year} {'NPRM ' if proposed else ''}RVU file" + return Cite("rvu_file", label, RVU_FILES_URL, locator=label) + + +def book_cite(item_key: str, edition_label: str, page_label: str) -> Cite: + """A page of a licensed book (cited, never quoted): ``" p. N"``, + or ``", "`` for a locator that is not a bare page + ("tab 10, PDF p. 4").""" + page = page_label.strip() + if re.fullmatch(r"\d+", page): + label = f"{edition_label} p. {page}" + elif re.fullmatch(r"p\.\s*\d+", page): + label = f"{edition_label} {page}" + else: + label = f"{edition_label}, {page}" + return Cite("cpt_book", label, "", item_key, locator=label) + + +def dataset_cite(item_key: str, label: str, url: str) -> Cite: + return Cite("dataset", label, url, item_key, locator=label) + + +def _cfr_url(locator: str) -> str: + from bib import cfrlink + + try: + return cfrlink.url(cfrlink.parse_cite(locator)) + except ValueError: + return "" + + +def reference_cite( + kind: str, locator: str, *, item_key: str = "", p_id: int = 0, page: int = 0 +) -> Cite: + """A CFR, IOM or MLN reference (``kind``), the eCFR link for a CFR cite; + *item_key*/*p_id* are the source that cites it.""" + url = _cfr_url(locator) if kind == "cfr" else "" + return Cite(kind, locator, url, item_key, p_id, page, locator) + + +def guidance_cite(row: Any) -> Cite: + """A ``pfs.code_guidance`` row (``GuidanceRow``): the reference itself, + keyed to the resolved bib item when there is one, else to the paragraph + that cites it.""" + return reference_cite( + row.kind, + row.locator, + item_key=row.item_key or row.item_key_src, + p_id=row.p_id_src, + page=row.page, + ) + + +_SSA_SECTION = re.compile(r"\bsection\s+(18\d\d[A-Z]?)(?=[\s(]|$)", re.I) +_OF_THE_ACT = re.compile(r"\bof\s+the\s+(?:Social\s+Security\s+)?Act\b", re.I) + + +def ssa_section_url(reference: str) -> str: + """The SSA compilation page of a title XVIII section the reference names + as "section 18NN… of the Act", else ``""``.""" + m = _SSA_SECTION.search(reference or "") + if m is None or not _OF_THE_ACT.search(reference): + return "" + return SSA_SECTION_URL.format(section=m.group(1).upper()) diff --git a/src/pfs/citecheck.py b/src/pfs/citecheck.py new file mode 100644 index 0000000..03f2467 --- /dev/null +++ b/src/pfs/citecheck.py @@ -0,0 +1,278 @@ +"""The sentence-level citation check on dossier prose (dossier task 13). + +Model-written prose reaches a page only when every sentence carries at least +one ``[F]`` tag naming a stored fact, every tag names a fact that exists, +and every number the sentence writes is a number its cited facts carry (in +their text or their values). A neighbour's number ("99342's 1.65" cited to +99341's round) is rejected; the same value written another way ("1.0" for +"1.00", "$131.17" for "131.17", "−16.5%" for "-16.5%") is accepted. +""" + +from __future__ import annotations + +import re +from dataclasses import dataclass +from typing import TYPE_CHECKING, Any, Iterable, Mapping + +if TYPE_CHECKING: # pragma: no cover + from pfs.dossier import Fact + +PROBLEM_KINDS = ("uncited", "unknown_fact", "number_mismatch") +#: what ``grounding_problems`` adds for model prose +GROUNDING_KINDS = ("ungrounded", "code_mismatch", "merged", "unattributed") + + +@dataclass(frozen=True) +class Problem: + sentence: str + kind: str # one of PROBLEM_KINDS + detail: str + + +# ── sentences ─────────────────────────────────────────────────────── + +#: tokens ending in a period that never end a sentence +_ABBREV = ( + "U.S.", + "e.g.", + "i.e.", + "No.", + "Nos.", + "p.", + "pp.", + "ch.", + "Ch.", + "vs.", + "Dr.", + "Mr.", + "Mrs.", + "Ms.", + "Inc.", + "Co.", + "Corp.", + "Jr.", + "Sr.", + "St.", + "al.", + "Vol.", + "Sec.", + "Fig.", + "approx.", +) +#: a sentence end: terminal punctuation (and a closing quote or bracket), +#: whitespace, then what can start a sentence +_END = re.compile(r"(?<=[.!?])[\"'”)]?\s+(?=[\[A-Z0-9“\"(¶§$])") +_TAG = re.compile(r"\[(F\d+(?:\s*,\s*F\d+)*)\]") +_LEADING_TAGS = re.compile(r"^((?:\[F\d+(?:\s*,\s*F\d+)*\]\s*)+)") + + +def _ends_with_abbrev(chunk: str) -> bool: + last = chunk.rsplit(None, 1)[-1] if chunk.split() else "" + last = last.lstrip("(\"'“") + return last in _ABBREV or bool(re.fullmatch(r"(?:[A-Z]\.){1,3}", last)) + + +def split_sentences(text: str) -> list[str]: + """Sentences of *text*. Abbreviations ("U.S.", "e.g.", "i.e.", "No.", + "p.") and decimals do not end a sentence; ``[F#]`` tags written after the + period stay with the sentence they close.""" + text = " ".join((text or "").split()) + if not text: + return [] + out: list[str] = [] + start = 0 + for m in _END.finditer(text): + chunk = text[start : m.start()].strip() + # the end match sits after the punctuation; a lone closing char is + # part of the sentence + chunk = text[start : m.end()].strip() + if _ends_with_abbrev(text[start : m.start() + 1]): + continue + out.append(chunk) + start = m.end() + out.append(text[start:].strip()) + # tags written after the period belong to the sentence before them + merged: list[str] = [] + for s in out: + lead = _LEADING_TAGS.match(s) + if lead and merged: + merged[-1] = f"{merged[-1]} {lead.group(1).strip()}" + s = s[lead.end() :].strip() + if s: + merged.append(s) + return merged + + +# ── numbers ───────────────────────────────────────────────────────── + +_BRACKETS = re.compile(r"\[[^\]]*\]") +_NUMBER = re.compile( + r"(?P\b[A-Z]\d{4}\b)" + r"|(?P\bCY\s?(?P\d{4})\b)" + r"|(?[-−–+]?\$?\d[\d,]*(?:\.\d+)?)" + r"(?P%|(?:st|nd|rd|th)\b)?" +) + + +def _norm_number(raw: str) -> str: + s = raw.replace("−", "-").replace("–", "-").replace("$", "") + s = s.replace(",", "").lstrip("+") + if "." in s: + s = s.rstrip("0").rstrip(".") + if s in ("-0", ""): + s = "0" + return s + + +def number_tokens(text: str) -> set[str]: + """The numbers *text* writes, normalized: bracketed segments (``[F3]``, + a cite label) removed first; ``$``, thousands commas and a leading ``+`` + dropped; ``−``/``–`` read as ``-``; trailing decimal zeros dropped + (``1.00`` → ``1``, ``3.60`` → ``3.6``); ``%`` and ordinal suffixes kept + (``25th``). ``CY2023`` gives ``2023``; a HCPCS code such as ``G0318`` is + one token; digits inside a word (``B1``, ``MOD1``) are not numbers; a + dash between two digits is a range, not a sign.""" + out: set[str] = set() + for m in _NUMBER.finditer(_BRACKETS.sub(" ", text or "")): + if m.group("code"): + out.add(m.group("code")) + elif m.group("cy"): + out.add(m.group("year")) + else: + out.add(_norm_number(m.group("num")) + (m.group("suffix") or "")) + return out + + +def _value_tokens(values: Mapping[str, Any]) -> set[str]: + out: set[str] = set() + for v in values.values(): + if isinstance(v, bool) or v is None: + continue + if isinstance(v, int | float): + out.add(_norm_number(f"{float(v):.6f}")) + else: + out |= number_tokens(str(v)) + return out + + +def _supported(facts: Iterable[Fact]) -> set[str]: + out: set[str] = set() + for f in facts: + out |= number_tokens(f.text) | _value_tokens(f.values) + return out + + +# ── the check ─────────────────────────────────────────────────────── + + +def tags_of(sentence: str) -> list[str]: + """The fact ids a sentence cites, in order (``[F1][F2]`` or ``[F1, F2]``).""" + return [t.strip() for m in _TAG.finditer(sentence) for t in m.group(1).split(",")] + + +def check_prose(prose: str, facts: Mapping[str, Fact]) -> list[Problem]: + """One :class:`Problem` per failing sentence of *prose*: ``uncited`` (no + ``[F#]`` tag), ``unknown_fact`` (a tag naming no fact in *facts*) or + ``number_mismatch`` (a number none of the sentence's cited facts carries). + ``[]`` means every sentence passed.""" + problems: list[Problem] = [] + for sentence in split_sentences(prose): + tags = tags_of(sentence) + if not tags: + problems.append(Problem(sentence, "uncited", "no [F#] tag")) + continue + unknown = [t for t in tags if t not in facts] + if unknown: + problems.append( + Problem(sentence, "unknown_fact", "no such fact: " + ", ".join(unknown)) + ) + continue + extra = number_tokens(sentence) - _supported(facts[t] for t in tags) + if extra: + problems.append( + Problem( + sentence, + "number_mismatch", + "not in the cited facts: " + ", ".join(sorted(extra)), + ) + ) + return problems + + +# ── grounding: the anti-goals a number check cannot see ───────────── + +#: words connective prose may use that a cited fact need not contain +_PROSE_GENERIC = frozenset( + "family families cms year years later then after before since first " + "following together respectively through value values both also rvu rvus".split() +) +_CODE5 = re.compile(r"\b\d{5}\b") + + +def grounding_problems(prose: str, facts: Mapping[str, Fact]) -> list[Problem]: + """What model prose must also respect beyond :func:`check_prose` (the + spec's anti-goals: no invented history, CMS's summary never merged with + our counts): every content word of a sentence occurs (stemmed) in the text + of the facts it cites, generic connective words aside (``ungrounded``); + every code it names, ranges expanded, is one those facts name + (``code_mismatch``); a sentence citing CMS's summary says "CMS" and one + citing our classification says "classified" (``unattributed``), and no + sentence cites both (``merged``). Sentences without a known tag are left + to ``check_prose``.""" + from pfs.guideline_facts import _GENERIC, _content, _stem + from pfs.lineage import _expand_ranges + + generic = {_stem(w) for w in _GENERIC | _PROSE_GENERIC} + out: list[Problem] = [] + for sentence in split_sentences(prose): + cited = [facts[t] for t in tags_of(sentence) if t in facts] + if not cited: + continue + body = _BRACKETS.sub(" ", sentence) + known = set().union(*(_content(f.text) for f in cited)) | generic + missing = sorted({w for w in _content(body) if w not in known}) + if missing: + out.append( + Problem( + sentence, + "ungrounded", + "words not in the cited facts: " + ", ".join(missing), + ) + ) + continue + # a range a fact itself writes may be restated + have = set().union( + *(set(f.codes) | set(_CODE5.findall(_expand_ranges(f.text))) for f in cited) + ) + extra = sorted(set(_CODE5.findall(_expand_ranges(body))) - have) + if extra: + out.append( + Problem( + sentence, + "code_mismatch", + "codes not in the cited facts: " + ", ".join(extra), + ) + ) + continue + kinds = {f.kind for f in cited} + if {"cms_summary", "stance_split"} <= kinds: + out.append( + Problem( + sentence, + "merged", + "CMS's summary and our classification in one sentence", + ) + ) + elif "cms_summary" in kinds and "CMS" not in body: + out.append( + Problem(sentence, "unattributed", "CMS's summary not attributed to CMS") + ) + elif "stance_split" in kinds and "classif" not in body.lower(): + out.append( + Problem( + sentence, + "unattributed", + 'our classification not labelled as ours ("we classified")', + ) + ) + return out diff --git a/src/pfs/codetables.py b/src/pfs/codetables.py index 44d586b..9f56ac8 100644 --- a/src/pfs/codetables.py +++ b/src/pfs/codetables.py @@ -6,6 +6,9 @@ ``pfs.code_family`` derived family membership with roles ``pfs.code_exposure`` the exposure calendar (#693): dated payable / revalued / status / ends / telehealth events +``pfs.dossier`` one assembled, checked dossier per family (task + 13; its writer and reader live in ``pfs.dossier``, + which builds on this module) ``pfs.cpt_*`` (docs/superpowers/specs/2026-09-09-cpt-canonical-schema-design.md §3) hold one CPT codebook edition's own organizing structure — @@ -665,6 +668,9 @@ CREATE TABLE IF NOT EXISTS pfs.commenter ( org_type VARCHAR, specialty VARCHAR, form_group VARCHAR, form_size INTEGER, basis VARCHAR, reg_category VARCHAR, extractor VARCHAR, family VARCHAR, submitter_name VARCHAR); +CREATE TABLE IF NOT EXISTS pfs.dossier ( + family VARCHAR, built_at TIMESTAMP, version INTEGER, json VARCHAR, + check_passed BOOLEAN, extractor VARCHAR); CREATE TABLE IF NOT EXISTS pfs.comment_stance ( family VARCHAR, item_key VARCHAR, docket VARCHAR, event_key VARCHAR, stance VARCHAR, reason VARCHAR, evidence VARCHAR, extractor VARCHAR, diff --git a/src/pfs/dossier.py b/src/pfs/dossier.py new file mode 100644 index 0000000..438c12b --- /dev/null +++ b/src/pfs/dossier.py @@ -0,0 +1,2514 @@ +"""The dossier of one code family: cited facts, computed gaps and checked +prose (dossier task 13; ``stack pfs dossier``). + +Everything Tasks 1-12 stored is read back and turned into :class:`Fact` rows, +each with one resolved :class:`~pfs.cite.Cite` (R10: the page never builds a +URL): origins and formation, lineage events, valuation rounds and PE notes, +CMS's own Comment:/Response: summaries, our classified stance counts (always +beside the method's measured accuracy), curated links, the payment table, +specialty impacts, money and seat stakes, and governance findings. The fact +text is fixed template copy filled from the row. A timeline groups the facts +by year and kind; the local model may write the summary and one line per +timeline event only from those facts, and every sentence it writes must pass +``pfs.citecheck.check_prose`` and ``grounding_problems`` (one retry with the +problems listed, then the template line). ``coverage`` states what the sources do not yet reach, +computed from the data, never constant. + +What never happens here: a proposed value presented as final (proposed values +come only from proposed-rule rows and say "proposed"); CMS's summary merged +with our counts (separate facts, separate cites); a lineage event a proposed +rule, a commenter's paragraph, a recap or a hypothetical states (dropped); a +commenter named from anything but the comment's own regulations.gov record +(``pfs.commenter``); licensed AMA text (CPT descriptors are never read; the +books give structured facts and flagged paraphrases). +""" + +from __future__ import annotations + +import datetime as _dt +import json +import logging +import re +from dataclasses import asdict, dataclass, field, replace +from typing import Any, Callable, Mapping, Sequence + +from pfs.cite import ( + Cite, + book_cite, + dataset_cite, + fr_page_cite, + fr_para_cite, + reference_cite, + rvu_cite, + ssa_section_url, +) +from pfs.citecheck import check_prose, grounding_problems, split_sentences +from pfs.codetables import ( + GuidelineFactRow, + OriginRow, + ReactionRow, + RoundRow, + ensure_tables, + is_missing_table_error, + read_cms_summaries, + read_commenters, + read_events, + read_guideline_facts, + read_origin, + read_psps, + read_reaction, + read_rounds, + read_seats, + read_specialty_impacts, + read_stances, +) +from pfs.descriptors import rule_year_of +from pfs.runlog import RunLog, input_hash + +__all__ = [ + "FACT_KINDS", + "Dossier", + "Excerpt", + "Fact", + "TimelineEvent", + "build_dossier", + "collect_facts", + "coverage", + "dossier_families", + "governance_excerpts", + "read_dossier", + "split_sentences", + "timeline", + "write_dossier", + "write_prose", +] + +log = logging.getLogger(__name__) + +FACT_KINDS = ( + "origin", + "formation", + "event", + "round", + "pe", + "cms_summary", + "stance_split", + "link", + "payment", + "impact", + "money", + "seat", + "finding", +) +_KIND_RANK = {k: i for i, k in enumerate(FACT_KINDS)} +#: shown flagged and queued for review (S2); never given to the model +UNREVIEWED = "model paraphrase, unreviewed" +UNREVIEWED_EXTRACT = "model extract, unreviewed" +DOSSIER_VERSION = 1 +PROSE_PROMPT_VERSION = "prose-v2" +#: only the specialties billing at least this share get money, impact and +#: seat facts (the expected-stance rule's own floor) +MIN_SHARE = 0.01 +MONEY_SPECIALTIES = 10 + + +# ── data ──────────────────────────────────────────────────────────── + + +@dataclass(frozen=True) +class Fact: + """One cited statement. ``values`` holds the row's own values (numbers + the citation check accepts beside the text, and labels such as + ``event_kind``); ``also`` further cites that support it (a final value's + proposal paragraph, a statute's SSA page); ``note`` flags a fact shown + for review ("model paraphrase, unreviewed").""" + + id: str + kind: str + year: int | None + codes: tuple[str, ...] + text: str + values: Mapping[str, float | str] + cite: Cite + also: tuple[Cite, ...] = () + note: str = "" + + +@dataclass(frozen=True) +class TimelineEvent: + year: int + kind: str + codes: tuple[str, ...] + what_changed: str + fact_ids: tuple[str, ...] + stance_fact_ids: tuple[str, ...] + cms_summary_fact_ids: tuple[str, ...] + + +@dataclass(frozen=True) +class Excerpt: + text: str + cite: Cite + + +@dataclass +class Dossier: + family: str + name: str + codes: tuple[str, ...] + status: str + years_active: str + summary: str + timeline: list[TimelineEvent] + rounds: list[dict] + payment: list[dict] + utilization: list[dict] + stakeholders: list[dict] + governance: list[Excerpt] + sources: dict[str, list[dict]] + gaps: list[str] + facts: dict[str, Fact] + built_at: str + check_passed: bool + extractor: str + #: facts shown flagged, for the S2 review queue: {fact_id, reason} + review: list[dict] = field(default_factory=list) + #: the summary and timeline lines that fell back to template copy + fallbacks: list[str] = field(default_factory=list) + #: the stance method's measured accuracy, shown beside every count + stance_accuracy: str = "" + version: int = DOSSIER_VERSION + + def to_json(self) -> str: + d = asdict(self) + d["facts"] = {k: _fact_dict(f) for k, f in self.facts.items()} + return json.dumps(d, ensure_ascii=False) + + @classmethod + def from_json(cls, s: str) -> Dossier: + d = json.loads(s) + d["codes"] = tuple(d["codes"]) + d["timeline"] = [ + TimelineEvent( + **{ + **e, + **{ + k: tuple(e[k]) + for k in ( + "codes", + "fact_ids", + "stance_fact_ids", + "cms_summary_fact_ids", + ) + }, + } + ) + for e in d["timeline"] + ] + d["governance"] = [ + Excerpt(e["text"], Cite(**e["cite"])) for e in d["governance"] + ] + d["facts"] = {k: _fact_from(v) for k, v in d["facts"].items()} + return cls(**d) + + +def _fact_dict(f: Fact) -> dict: + d = asdict(f) + d["values"] = dict(f.values) + return d + + +def _fact_from(d: Mapping[str, Any]) -> Fact: + return Fact( + id=d["id"], + kind=d["kind"], + year=d["year"], + codes=tuple(d["codes"]), + text=d["text"], + values=dict(d["values"]), + cite=Cite(**d["cite"]), + also=tuple(Cite(**c) for c in d.get("also") or ()), + note=d.get("note", ""), + ) + + +def _draft( + kind: str, + year: int | None, + codes: Sequence[str], + text: str, + cite: Cite, + values: Mapping[str, Any] | None = None, + also: Sequence[Cite] = (), + note: str = "", +) -> Fact: + return Fact( + "", kind, year, tuple(codes), text, dict(values or {}), cite, tuple(also), note + ) + + +def _order_key(f: Fact) -> tuple: + return (f.year or 0, _KIND_RANK.get(f.kind, len(_KIND_RANK)), f.codes[:1], f.text) + + +# ── small helpers ─────────────────────────────────────────────────── + + +def _rows(read: Callable[..., Any], *args: Any, **kwargs: Any) -> list: + """*read*'s rows, ``[]`` when its table is not on the replica yet.""" + try: + return list(read(*args, **kwargs)) + except Exception as exc: # noqa: BLE001 - only a missing table is tolerated + if is_missing_table_error(exc): + return [] + raise + + +def compact(codes: Sequence[str]) -> str: + """ "99324–99328, 99334–99337 and 99343": runs of three or more + consecutive numeric codes become an en-dash range.""" + cs = sorted(set(codes)) + out: list[str] = [] + i = 0 + while i < len(cs): + j = i + while ( + j + 1 < len(cs) + and cs[j].isdigit() + and cs[j + 1].isdigit() + and int(cs[j + 1]) == int(cs[j]) + 1 + ): + j += 1 + if j - i >= 2: + out.append(f"{cs[i]}–{cs[j]}") + else: + out += cs[i : j + 1] + i = j + 1 + return _join_and(out) + + +def _join_and(items: Sequence[str]) -> str: + items = list(items) + if len(items) <= 1: + return "".join(items) + return ", ".join(items[:-1]) + " and " + items[-1] + + +def _rvu(v: float) -> str: + return f"{v:.2f}" + + +def _pct(x: float) -> str: + """A fraction as a percent the way CMS prints it: 0.01 -> "1%", + -0.005 -> "-0.5%".""" + return f"{round(x * 100, 1):g}%" + + +def _expand_range(code: str, members: Sequence[str]) -> tuple[str, ...]: + m = re.fullmatch(r"(\d{5})-(\d{5})", code) + if m is None: + return (code,) if code in members else () + lo, hi = m.groups() + return tuple(c for c in sorted(members) if lo <= c <= hi) + + +class _Bib: + """Cached reads of the bib store: rule kind and year per item, paragraph + text, item titles.""" + + def __init__(self, store: Any) -> None: + self.store = store + self._rules: dict[str, tuple[str, int | None]] = {} + self._paras: dict[tuple[str, int], str | None] = {} + + def rule(self, item_key: str) -> tuple[str, int | None]: + if item_key not in self._rules: + from bib.frlink import rule_kind + + row = ( + self.store._con() # noqa: SLF001 + .execute( + "SELECT title, date_published FROM items WHERE key = ?", + (item_key,), + ) + .fetchone() + ) + if row is None: + self._rules[item_key] = ("", None) + else: + title, dp = row[0] or "", row[1] or "" + self._rules[item_key] = ( + rule_kind(self.store, item_key, title=title), + rule_year_of(title, dp), + ) + return self._rules[item_key] + + def paragraph(self, item_key: str, p_id: int) -> str | None: + key = (item_key, p_id) + if key not in self._paras: + row = ( + self.store._con() # noqa: SLF001 + .execute( + "SELECT text FROM fr_anchors WHERE item_key = ? AND p_id = ?", + key, + ) + .fetchone() + ) + self._paras[key] = (row[0] or "") if row else None + return self._paras[key] + + def title(self, item_key: str) -> str: + row = ( + self.store._con() # noqa: SLF001 + .execute("SELECT title FROM items WHERE key = ?", (item_key,)) + .fetchone() + ) + return (row[0] or "") if row else "" + + +# ── fixed template copy ───────────────────────────────────────────── + + +def round_text( + year: int, + code: str, + *, + ruc: float | None = None, + final: float | None = None, + decision: str = "", + proposed: float | None = None, +) -> str: + """One valuation round's sentence: the RUC recommendation against CMS's + final value (a final rule), else CMS's proposal (a proposed rule).""" + if ruc is not None and final is not None: + tail = f" ({decision})" if decision else "" + return ( + f"For CY{year}, the RUC recommended a work RVU of {_rvu(ruc)} for " + f"{code} and CMS finalized {_rvu(final)}{tail}." + ) + if final is not None: + return f"For CY{year}, CMS finalized a work RVU of {_rvu(final)} for {code}." + if proposed is not None: + return f"For CY{year}, CMS proposed a work RVU of {_rvu(proposed)} for {code}." + if ruc is not None: + return ( + f"For CY{year}, the RUC recommended a work RVU of {_rvu(ruc)} for {code}." + ) + return "" + + +_QUANTIFIER = { + "majority": "a majority of", + "many": "many", + "several": "several", + "some": "some", + "few": "a few", + "one": "one", + "all": "all", + "unspecified": "", +} +_STANCE_PHRASE = { + "support": "supported the proposal", + "modify": "asked for changes", + "oppose": "opposed the proposal", + "mixed": "were divided", + "unclear": "commented", +} + + +def cms_summary_text(quantifier: str, stance: str, year: int, kind: str) -> str: + """CMS's own characterization of the commenters, as CMS's: "CMS reported + that a majority of commenters supported the proposal (CY2023 final + rule)." One commenter reads in the singular ("gave a mixed view").""" + phrase = _STANCE_PHRASE.get(stance, "commented") + if quantifier == "one": + who = "one commenter" + if stance == "mixed": + phrase = "gave a mixed view" + else: + who = " ".join(f"{_QUANTIFIER.get(quantifier, '')} commenters".split()) + return f"CMS reported that {who} {phrase} (CY{year} {kind} rule)." + + +def stance_split_text( + n: int, year: int, event_text: str, s: int, m: int, o: int, u: int +) -> str: + return ( + f"Of {n} CY{year} commenters we classified on {event_text}, {s} supported, " + f"{m} asked for modifications, {o} opposed and {u} were unclear." + ) + + +_EVENT_TEXT = { + "deleted": "{code} was deleted for CY{year}.", + "cpt_panel": "{code} was acted on by the CPT Editorial Panel for CY{year}.", + "disappeared": "{code} no longer appears in the PFS RVU file from CY{year}.", + "misvalued": "{code} was named as potentially misvalued for CY{year}.", + "created": "{code} was created for CY{year}.", + "replaced_by": "{code} was replaced by {to} for CY{year}.", + "replaces": "{code} replaced {from_} for CY{year}.", + "crosswalk": "{code} was crosswalked to {to} for CY{year}.", + # R?: a telehealth_list lineage row can rest on a base-code mention (a + # known T2 defect): never "added to the list", only where it is named + "telehealth_list": "{code} is named in a telehealth-list paragraph of the CY{year} rule.", + "appeared": "{code} first appears in the PFS RVU file in CY{year}.", + "revalued": "{code}'s non-facility total RVUs changed by {note} in the CY{year} RVU file.", + "status_change": "{code}'s payment status changed ({note}) in the CY{year} RVU file.", + # the RVU file's short descriptor is AMA text: the change is stated, the + # text never shown + "descriptor_change": "{code}'s short descriptor in the PFS RVU file changed for CY{year}.", + "bundled": "{code} was bundled for CY{year}.", +} +#: the plural of a template, for a timeline line naming several codes +_EVENT_PLURAL = { + "deleted": "{codes} were deleted for CY{year}", + "cpt_panel": "{codes} were acted on by the CPT Editorial Panel for CY{year}", + "disappeared": "{codes} no longer appear in the PFS RVU file from CY{year}", + "misvalued": "{codes} were named as potentially misvalued for CY{year}", + "created": "{codes} were created for CY{year}", + "telehealth_list": "{codes} are named in a telehealth-list paragraph of the CY{year} rule", + "appeared": "{codes} first appear in the PFS RVU file in CY{year}", + "descriptor_change": "The short descriptors of {codes} in the PFS RVU file changed for CY{year}", + "bundled": "{codes} were bundled for CY{year}", +} +EVENT_KINDS = tuple(_EVENT_TEXT) + + +def event_fact_text( + kind: str, + code: str, + year: int, + *, + to: Sequence[str] = (), + from_: Sequence[str] = (), + note: str = "", +) -> str: + return _EVENT_TEXT[kind].format( + code=code, year=year, to=_join_and(to), from_=_join_and(from_), note=note + ) + + +def link_text(year: int, target: str, kind: str) -> str: + return f"From CY{year}, {target} can be reported with this family ({kind})." + + +# ── stance accuracy (R66a, R81, conditions) ───────────────────────── + + +def stance_accuracy_line(ev: Mapping[str, Any] | None) -> str: + """The stance method's measurement, shown beside every count: recall and + direction with the n behind them, labelled held-out or tuning set and + scoped by the dockets measured (never presented as one docket's own + accuracy).""" + if not ev: + return "Preliminary model classification; its accuracy is not yet measured." + where = ", ".join(ev.get("dockets") or [d for d in [ev.get("docket", "")] if d]) + scope = ( + "on the tuning set" + if ev.get("in_sample", True) + else "on a held-out set the prompt was never tuned on" + ) + return ( + f"Preliminary model classification, measured {scope} ({ev['n_items']} " + f"hand-coded comments, {ev['n_positions']} positions; {where}): it finds " + f"{round(ev['recall'] * 100)}% of hand-coded positions, and the direction " + f"is right for {round(ev['direction'] * 100)}% of those it finds." + ) + + +def _in_sample_line(ev: Mapping[str, Any]) -> str: + rec = ev.get("in_sample_record") + if not rec: + return "" + return ( + " Tuning-set record: " + + stance_accuracy_line({**rec, "in_sample": True}).split( + ", measured on the tuning set " + )[1] + ) + + +# ── money and seats wording (conditions: T10, T11) ────────────────── + + +def money_change(delta: float | None, *, lower_bound: bool) -> str: + """A payment change in words: never "at least $-X" (R83).""" + if delta is None: + return "" + amount = round(abs(delta)) + if amount == 0: + return "no change" + floor = "at least " if lower_bound else "" + what = "a cut" if delta < 0 else "an increase" + return f"{what} of {floor}${amount:,}" + + +def roster_year(captured: set[int], year: int) -> tuple[int | None, str]: + """R91: the RUC roster that valued rule year *year* is the year before + (the RUC that valued CY2023 met in 2022); the year itself when only that + is captured. ``(roster year, what the text says about it)``.""" + if year - 1 in captured: + return year - 1, f" (the RUC that valued CY{year} met in {year - 1})" + if year in captured: + return year, ( + f" (the roster of CY{year} itself; the {year - 1} roster is not captured)" + ) + return None, "" + + +# ── facts: origin, formation and the books ────────────────────────── + +_CFR_IN = re.compile(r"\b\d+ CFR \d+") + + +def _real_reference(row: OriginRow) -> bool: + """R93: a CFR cite naming a title-42 part that does not exist is an FR + typo ("42 CFR 25.400" for 425.400) and states nothing.""" + from pfs.origin import _real_cfr + + for text in (row.reference, row.locator): + for m in _CFR_IN.finditer(text or ""): + if not _real_cfr(m.group(0)): + return False + return True + + +def _origin_shape(r: OriginRow) -> str: + """A deterministic per-code summary with its code masked, so rows that + differ only in the code consolidate; a model summary stays as written.""" + if r.extractor in ("lineage", "guidance"): + return re.sub(rf"\b{re.escape(r.code)}\b", "\x00", r.summary) + return r.summary + + +def _book_edition(bib: _Bib, item_key: str, fallback: str) -> str: + title = bib.title(item_key) + return title or fallback + + +def _origin_facts(con: Any, bib: _Bib, family: Any) -> list[Fact]: + groups: dict[tuple, list[OriginRow]] = {} + for r in _rows(read_origin, con, family.key): + if not _real_reference(r): + continue + key = ( + r.kind, + r.reference, + r.year, + r.cite_kind, + r.item_key, + r.p_id, + r.ref_p_id, + r.locator, + _origin_shape(r), + ) + groups.setdefault(key, []).append(r) + out: list[Fact] = [] + for ( + kind, + ref, + year, + cite_kind, + item_key, + p_id, + ref_p_id, + loc, + shape, + ), rows in groups.items(): + codes = sorted({r.code for r in rows}) + text = shape.replace("\x00", compact(codes)) + also: list[Cite] = [] + if cite_kind == "fr_para": + cite = fr_para_cite(bib.store, item_key, p_id) + if ref_p_id and ref_p_id != p_id: + also.append(fr_para_cite(bib.store, item_key, ref_p_id)) + elif cite_kind == "cpt_book": + m = re.match(r"(.+?),\s*(p\.\s*\S.*)$", loc or "") + edition, page = (m.group(1), m.group(2)) if m else (loc, rows[0].page_label) + cite = book_cite(item_key, edition, page) + elif shape.startswith("CMS guidance for"): + cite = reference_cite(cite_kind, ref, item_key=item_key, p_id=p_id) + if p_id: + also.append(fr_para_cite(bib.store, item_key, p_id)) + else: + cite = fr_para_cite(bib.store, item_key, p_id) + also.append( + reference_cite(cite_kind, ref, item_key=item_key, p_id=ref_p_id) + ) + if kind == "statute" and (url := ssa_section_url(ref)): + also.append(Cite("statute", ref, url, locator=ref)) + fact_kind = "formation" if kind in ("cpt_panel", "cms_gcode") else "origin" + out.append( + _draft(fact_kind, year, codes, text, cite, {"origin_kind": kind}, also) + ) + return out + + +_BASIS = { + "history_exam_mdm": "is selected on history, examination and medical decision making", + "mdm_or_time": "is selected on medical decision making or total time", +} +_STRUCTURED = ( + "selection_basis", + "mdm_level", + "time_threshold_min", + "typical_time_min", + "addon", +) + + +def _profile_text(code: str, edition: int, profile: Mapping[str, str]) -> str: + extras = [] + if "mdm_level" in profile: + extras.append(f"with {profile['mdm_level']} medical decision making") + if "time_threshold_min" in profile: + extras.append(f"a time threshold of {profile['time_threshold_min']} minutes") + if "typical_time_min" in profile: + extras.append(f"a typical time of {profile['typical_time_min']} minutes") + if profile.get("addon") == "true": + extras.append("add-on status") + basis = profile.get("selection_basis") + head = f"In the CPT {edition} codebook, {code}" + if basis: + head += " " + _BASIS.get(basis, f"is selected on {basis.replace('_', ' ')}") + return head + (", " + _join_and(extras) if extras else "") + "." + return f"{head} carries {_join_and(extras)}." + + +def _guideline_facts(con: Any, bib: _Bib, family: Any) -> list[Fact]: + rows: list[GuidelineFactRow] = _rows(read_guideline_facts, con, family.key) + members = family.codes + out: list[Fact] = [] + + def cite_of(r: GuidelineFactRow) -> Cite: + edition = _book_edition(bib, r.cite_item, f"CPT {r.edition_year}") + return book_cite(r.cite_item, edition, r.cite_locator) + + profiles: dict[str, dict[int, tuple[dict[str, str], GuidelineFactRow]]] = {} + deleted: dict[tuple, list[str]] = {} + for r in rows: + if r.fact in _STRUCTURED: + prof, _first = profiles.setdefault(r.code, {}).setdefault( + r.edition_year, ({}, r) + ) + prof[r.fact] = r.value + elif r.fact == "deleted_in_edition": + # edition_year = the code set that dropped it; value = the last + # edition that still lists it + deleted.setdefault( + (r.edition_year, r.value, r.cite_item, r.cite_locator), [] + ).append(r.code) + else: # scope_point, panel_action: paraphrases, shown flagged + out.append( + _draft( + "formation", + r.edition_year, + _expand_range(r.code, members), + r.value, + cite_of(r), + {"guideline": r.fact}, + note=UNREVIEWED, + ) + ) + for code, by_edition in profiles.items(): + before: dict[str, str] | None = None + for edition in sorted(by_edition): + prof, first = by_edition[edition] + if prof != before: + out.append( + _draft( + "formation" if before is None else "event", + edition, + (code,), + _profile_text(code, edition, prof), + cite_of(first), + {"event_kind": "cpt_edition"}, + ) + ) + before = prof + for (year, value, item, loc), codes in deleted.items(): + last = f" (last listed in the {value} edition)" if value.isdigit() else "" + out.append( + _draft( + "formation", + year, + sorted(codes), + f"CPT deleted {compact(codes)} in its {year} code set{last}.", + book_cite(item, _book_edition(bib, item, f"CPT {year}"), loc), + {"event_kind": "cpt_deleted"}, + ) + ) + return out + + +# ── facts: lineage events ─────────────────────────────────────────── + +#: a sentence that only recounts or conditions a change states none +_NOT_STATED = re.compile( + r"\b(?:we|CMS)\s+(?:had\s+)?proposed\b|\bif\s+(?:this|the|our|these)\s+proposals?\b", + re.I, +) +#: the word a sentence must carry to state an event of that kind +_EVENT_VERB = { + "created": re.compile(r"\b(?:creat|establish)\w*", re.I), + "replaced_by": re.compile(r"\breplac\w*", re.I), + "replaces": re.compile(r"\breplac\w*", re.I), + "crosswalk": re.compile(r"\bcrosswalk\w*", re.I), + "misvalued": re.compile(r"\bmisvalu\w*", re.I), + "bundled": re.compile(r"\bbundl\w*", re.I), + "telehealth_list": re.compile(r"\btelehealth\b", re.I), +} +_EARLIEST_ONLY = frozenset({"created", "appeared", "deleted", "disappeared"}) +_RVU_KINDS = frozenset( + {"disappeared", "appeared", "revalued", "status_change", "descriptor_change"} +) +_DIRECTIONAL = frozenset({"replaced_by", "replaces", "crosswalk"}) + + +def _event_stated(bib: _Bib, e: Any) -> bool: + """An FR lineage row stands only on a final rule's paragraph (never a + proposal), not a commenter's ("Comment:"), with a plain sentence naming + the code that reads as the event: no recap of another year's rule, no + hypothetical or request, no "we proposed"/"if this proposal".""" + from pfs.lineage import deletion_readings + from pfs.origin import _names, _plain + from pfs.rounds import _sentences + + kind, rule_year = bib.rule(e.item_key) + if kind != "final": + return False + text = bib.paragraph(e.item_key, e.p_id) + if not text or text.lstrip().startswith("Comment:"): + return False + if e.kind == "telehealth_list": + # stated neutrally ("named in a telehealth-list paragraph"): the + # paragraph names the code and is about the telehealth list + return _names(text, e.code) and bool(_EVENT_VERB[e.kind].search(text)) + others = (e.to_codes or e.from_codes).split() + for s in _sentences(text): + if not _names(s, e.code) or not _plain(s, rule_year) or _NOT_STATED.search(s): + continue + if e.kind in ("deleted", "cpt_panel"): + if e.kind in deletion_readings(s, e.code): + return True + continue + verb = _EVENT_VERB.get(e.kind) + if verb is not None and not verb.search(s): + continue + if others and not any(_names(s, c) for c in others): + continue + return True + return False + + +def _known_codes(con: Any, family: Any) -> set[str]: + known = set(family.codes) | {ln.target for ln in family.links} + try: + known |= { + r[0] for r in con.execute("SELECT DISTINCT hcpcs FROM pfs.rvu").fetchall() + } + except Exception as exc: # noqa: BLE001 + if not is_missing_table_error(exc): + raise + return known + + +def _event_facts(con: Any, bib: _Bib, family: Any) -> list[Fact]: + since = {ln.target: ln.since or 0 for ln in family.links} + known = _known_codes(con, family) + kept: dict[tuple, Any] = {} + for code in [*family.codes, *since]: + for e in _rows(read_events, con, code): + if e.kind not in _EVENT_TEXT: + continue + if code in since and e.year < since[code]: + continue # R92: a recycled G-code's earlier life + if e.source == "rvu": + if e.kind not in _RVU_KINDS: + continue + elif e.source != "fr" or not _event_stated(bib, e): + continue + to = tuple(c for c in e.to_codes.split() if c in known) + frm = tuple(c for c in e.from_codes.split() if c in known) + if e.kind in _DIRECTIONAL and not (to or frm): + continue + key = (code, e.year, e.kind, to, frm) + prior = kept.get(key) + if prior is None or (e.p_id, e.item_key) < ( + prior[0].p_id, + prior[0].item_key, + ): + kept[key] = (e, to, frm) + # point-in-time kinds once per code, at the earliest year + first: dict[tuple[str, str], int] = {} + for code, year, kind, _to, _frm in kept: + if kind in _EARLIEST_ONLY: + first[(code, kind)] = min(year, first.get((code, kind), year)) + out: list[Fact] = [] + for (code, year, kind, to, frm), (e, _t, _f) in sorted(kept.items()): + if kind in _EARLIEST_ONLY and year != first[(code, kind)]: + continue + note = e.note if kind in ("revalued", "status_change") else "" + cite = ( + rvu_cite(year) + if e.source == "rvu" + else fr_para_cite(bib.store, e.item_key, e.p_id) + ) + values: dict[str, Any] = {"event_kind": kind} + if note: + values["change"] = note + out.append( + _draft( + "event", + year, + (code,), + event_fact_text(kind, code, year, to=to, from_=frm, note=note), + cite, + values, + ) + ) + return out + + +# ── facts: links ──────────────────────────────────────────────────── + + +def _link_facts(bib: _Bib, family: Any) -> list[Fact]: + out: list[Fact] = [] + for ln in family.links: + if ln.since is None: + continue + if ln.p_id: + cite = fr_para_cite(bib.store, ln.item_key, ln.p_id) + elif ln.page: + cite = fr_page_cite(bib.store, ln.item_key, ln.page) + else: + cite = rvu_cite(ln.rvu_year) + out.append( + _draft( + "link", + ln.since, + (ln.target,), + link_text(ln.since, ln.target, ln.kind), + cite, + {"link_kind": ln.kind}, + ) + ) + for alias in ln.aliases: + _kind, year = bib.rule(ln.alias_item_key) + out.append( + _draft( + "link", + ln.since, + (ln.target,), + f"In the CY{year or ln.since} proposed rule, {ln.target} was the " + f"placeholder code {alias}.", + fr_para_cite(bib.store, ln.alias_item_key, ln.alias_p_id), + {"alias": alias}, + ) + ) + return out + + +# ── facts: valuation rounds and PE ────────────────────────────────── + +_PERCENTILE = {"25th": "25th percentile", "median": "median"} + + +def _table_no(title: str) -> str: + m = re.match(r"\s*(Table \d+)", title or "") + return m.group(1) if m else "" + + +def _round_cite(bib: _Bib, r: RoundRow, field_name: str) -> tuple[Cite, list[Cite]]: + """The cite of one round field (R27 ``field_cites``: a paragraph, an FR + table page "page:N", or a list of paragraphs), falling back to the row's + own anchors.""" + cites = json.loads(r.field_cites or "{}") + v = cites.get(field_name) + if isinstance(v, str) and v.startswith("page:"): + return fr_page_cite( + bib.store, r.item_key, int(v[5:]), table=_table_no(r.table_title) + ), [] + if isinstance(v, list) and v: + return fr_para_cite(bib.store, r.item_key, int(v[0])), [ + fr_para_cite(bib.store, r.item_key, int(p)) for p in v[1:] + ] + if isinstance(v, int) and v: + return fr_para_cite(bib.store, r.item_key, v), [] + if r.p_id: + return fr_para_cite(bib.store, r.item_key, r.p_id), [] + return fr_page_cite( + bib.store, r.item_key, r.page, table=_table_no(r.table_title) + ), [] + + +def _round_facts(bib: _Bib, rounds: Sequence[RoundRow]) -> list[Fact]: + out: list[Fact] = [] + done: set[tuple] = set() + finals = {(r.code, r.rule_year) for r in rounds if r.rule_kind == "final"} + + def once(key: tuple) -> bool: + if key in done: + return False + done.add(key) + return True + + ordered = sorted( + rounds, key=lambda r: (r.rule_year, r.code, r.rule_kind != "final") + ) + for r in ordered: + year, code = r.rule_year, r.code + if r.rule_kind == "final": + ruc = r.ruc_work_rvu + text = round_text( + year, code, ruc=ruc, final=r.final_work_rvu, decision=r.decision + ) + if text: + field_name = ( + "final_work_rvu" if r.final_work_rvu is not None else "ruc_work_rvu" + ) + cite, also = _round_cite(bib, r, field_name) + seen = {(cite.item_key, cite.p_id, cite.page)} + for other in ("ruc_work_rvu", "proposed_work_rvu"): + c, more = _round_cite(bib, r, other) + for x in (c, *more): + if (x.item_key, x.p_id, x.page) not in seen: + seen.add((x.item_key, x.p_id, x.page)) + also.append(x) + values = { + k: v + for k, v in ( + ("ruc", ruc), + ("final", r.final_work_rvu), + ("decision", r.decision), + ) + if v not in (None, "") + } + out.append(_draft("round", year, (code,), text, cite, values, also)) + if ruc is not None: + done.add((code, year)) + elif r.rule_kind == "proposed": + if r.proposed_work_rvu is not None: + cite, also = _round_cite(bib, r, "proposed_work_rvu") + out.append( + _draft( + "round", + year, + (code,), + round_text(year, code, proposed=r.proposed_work_rvu), + cite, + {"proposed": r.proposed_work_rvu}, + also, + ) + ) + if ( + r.ruc_work_rvu is not None + and (code, year) not in finals + and once((code, year)) + ): + cite, also = _round_cite(bib, r, "ruc_work_rvu") + out.append( + _draft( + "round", + year, + (code,), + round_text(year, code, ruc=r.ruc_work_rvu), + cite, + {"ruc": r.ruc_work_rvu}, + also, + ) + ) + else: + continue + if r.ruc_percentile in _PERCENTILE and once(("pct", code, year)): + cite, also = _round_cite(bib, r, "ruc_percentile") + out.append( + _draft( + "round", + year, + (code,), + f"For CY{year}, the RUC recommended the survey " + f"{_PERCENTILE[r.ruc_percentile]} value for {code}.", + cite, + {"percentile": r.ruc_percentile}, + also, + ) + ) + for fld, what in ( + ("survey_total_min", "total"), + ("survey_intra_min", "intra-service"), + ): + v = getattr(r, fld) + if v is not None and once((fld, code, year)): + cite, also = _round_cite(bib, r, fld) + out.append( + _draft( + "round", + year, + (code,), + f"For CY{year}, the RUC survey {what} time for {code} was " + f"{v:g} minutes.", + cite, + {fld: v}, + also, + ) + ) + if r.requested_work_rvu is not None and once(("req", code, year)): + cite, also = _round_cite(bib, r, "requested_work_rvu") + out.append( + _draft( + "round", + year, + (code,), + f"For CY{year}, commenters requested a work RVU of " + f"{_rvu(r.requested_work_rvu)} for {code}.", + cite, + {"requested": r.requested_work_rvu}, + also, + ) + ) + if r.comparators.strip() and once(("cmp", code, year)): + cite, also = _round_cite(bib, r, "comparators") + out.append( + _draft( + "round", + year, + (code,), + f"For CY{year}, the comparator codes named for {code} were " + f"{r.comparators.strip()}.", + cite, + {}, + also, + ) + ) + return out + + +def _pe_clause(note: str) -> str: + parts = [p.strip() for p in note.split(";") if p.strip()] + pick = next((p for p in parts if p.lower().startswith("finaliz")), parts[0]) + if len(pick) > 240: + pick = pick[:240].rsplit(" ", 1)[0] + return pick.rstrip(".") + + +def _pe_facts(bib: _Bib, rounds: Sequence[RoundRow]) -> list[Fact]: + out = [] + for r in rounds: + if not r.pe_note.strip() or r.rule_kind not in ("final", "proposed"): + continue + cite, also = _round_cite(bib, r, "pe_note") + out.append( + _draft( + "pe", + r.rule_year, + (r.code,), + f"CY{r.rule_year} {r.rule_kind} rule, direct PE inputs for {r.code}: " + f"{_pe_clause(r.pe_note)}.", + cite, + {"rule_kind": r.rule_kind}, + also, + note=UNREVIEWED_EXTRACT, + ) + ) + return out + + +def _round_dicts(bib: _Bib, rounds: Sequence[RoundRow]) -> list[dict]: + """The valuation panel's rows: every non-empty field (an empty column is + never shown as a value), each value field's resolved cite and the + rationale paragraph's link (R10).""" + out = [] + for r in rounds: + d = { + k: v + for k, v in asdict(r).items() + if v not in (None, "") and k not in ("field_cites", "extractor", "family") + } + d["cites"] = { + f: asdict(_round_cite(bib, r, f)[0]) + for f in json.loads(r.field_cites or "{}") + } + if r.rationale_p_id: + d["rationale"] = asdict( + fr_para_cite(bib.store, r.item_key, r.rationale_p_id) + ) + out.append(d) + return out + + +# ── facts: CMS's summaries and our stance counts (kept apart) ─────── + + +def _cms_facts(con: Any, bib: _Bib, family: Any) -> list[Fact]: + out = [] + for r in _rows(read_cms_summaries, con, family.key): + out.append( + _draft( + "cms_summary", + r.rule_year, + tuple(c for c in r.codes.split(",") if c), + cms_summary_text(r.quantifier, r.stance, r.rule_year, r.rule_kind), + fr_para_cite(bib.store, r.item_key, r.comment_p_id), + { + "quantifier": r.quantifier, + "stance": r.stance, + "response_action": r.response_action, + }, + [fr_para_cite(bib.store, r.item_key, r.response_p_id)], + ) + ) + return out + + +def event_label(slug: str) -> str: + return { + "valuation": "the work RVU valuation", + "coding": "the coding changes", + "telehealth": "the telehealth-list status of the family's codes", + "other": "other aspects of the family's codes", + }.get(slug, f"the linked code {slug}") + + +def _event_year(key: str) -> int: + parts = key.split(":") + return int(parts[-2]) if len(parts) >= 3 and parts[-2].isdigit() else 0 + + +def _classified(con: Any, family: Any) -> list[ReactionRow]: + """Docket rows whose stances were classified (``n_classified`` NULL means + never classified: no count is shown, never 0/0).""" + return [ + r + for r in _rows(read_reaction, con, family.key) + if r.period_kind == "docket" and r.n_classified is not None + ] + + +def _eval(r: ReactionRow) -> dict | None: + return json.loads(r.stance_eval) if r.stance_eval else None + + +def _stance_facts(con: Any, family: Any) -> list[Fact]: + out = [] + for r in _classified(con, family): + events = json.loads(r.events_json or "{}") + years = [_event_year(k) for k in events if _event_year(k)] + year = min(years) if years else r.year + ev = _eval(r) + acc = stance_accuracy_line(ev) + cite = dataset_cite( + "", + f"Our classification of docket {r.period} comments", + f"https://www.regulations.gov/docket/{r.period}", + ) + base = {"docket": r.period} + if ev: + base.update(recall=ev["recall"], direction=ev["direction"]) + for key, c in events.items(): + slug = key.split(":")[-1] + s, m, o, u = ( + c.get(k, 0) for k in ("support", "modify", "oppose", "unclear") + ) + out.append( + _draft( + "stance_split", + _event_year(key) or year, + (), + stance_split_text( + s + m + o + u, + _event_year(key) or year, + event_label(slug), + s, + m, + o, + u, + ) + + " " + + acc, + cite, + { + **base, + "event_key": key, + "support": s, + "modify": m, + "oppose": o, + "unclear": u, + }, + ) + ) + u = r.stance_unclear + verb = "was" if u == 1 else "were" + out.append( + _draft( + "stance_split", + year, + (), + f"Of {r.n_commenters} CY{year} commenters on this family in docket " + f"{r.period}, we classified {r.n_classified} with a firm position: " + f"{r.stance_support} supported, {r.stance_modify} asked for " + f"modifications and {r.stance_oppose} opposed; {u} more {verb} " + f"unclear. {acc}", + cite, + { + **base, + "event_key": "", + "n_commenters": r.n_commenters or 0, + "n_classified": r.n_classified or 0, + }, + ) + ) + return out + + +# ── payment, impacts, money, seats ────────────────────────────────── + + +def _payment_rows(con: Any, family: Any) -> list[Any]: + from pfs.valuation import valuation + + since = {ln.target: ln.since or 0 for ln in family.links} + try: + rows, _unpriced = valuation( + con, [*family.codes, *since], years=0, all_proposed=True + ) + except Exception as exc: # noqa: BLE001 + if is_missing_table_error(exc): + return [] + raise + return [r for r in rows if r.code not in since or r.year >= since[r.code]] + + +def _payment_dict(r: Any) -> dict: + d = asdict(r) + d.pop("description", None) # the RVU file's short descriptor is AMA text + return d + + +def _payment_facts(rows: Sequence[Any]) -> list[Fact]: + out = [] + for r in rows: + if r.pay_nf is None: + text = ( + f"For CY{r.year}, {r.code} carried payment status {r.status or 'blank'}, " + f"so no national payment is computed." + ) + elif r.proposed: + text = ( + f"For CY{r.year}, CMS proposed a national non-facility payment of " + f"${r.pay_nf:,.2f} for {r.code} ({_rvu(r.total_nf)} non-facility total " + f"RVUs at a proposed conversion factor of ${r.cf:.4f})." + ) + else: + text = ( + f"For CY{r.year}, the national non-facility payment for {r.code} was " + f"${r.pay_nf:,.2f} ({_rvu(r.total_nf)} non-facility total RVUs at a " + f"conversion factor of ${r.cf:.4f})." + ) + also = ( + [Cite("fr_page", r.citation, r.url, locator=r.citation)] + if r.citation + else [] + ) + values = { + k: v + for k, v in ( + ("pay_nf", r.pay_nf), + ("work", r.work), + ("total_nf", r.total_nf), + ("cf", r.cf), + ) + if v is not None + } + values["vintage"] = r.vintage + out.append( + _draft( + "payment", + r.year, + (r.code,), + text, + rvu_cite(r.year, proposed=r.proposed), + values, + also, + ) + ) + return out + + +def _specialty_vocab(con: Any, fallback: set[str]) -> set[str]: + from pfs.commenters import specialty_vocab + + try: + return set(specialty_vocab(con)) + except Exception as exc: # noqa: BLE001 + if is_missing_table_error(exc): + return fallback + raise + + +def _impact_rows(con: Any, years: Sequence[int]) -> list[Any]: + return [ + r + for r in _rows(read_specialty_impacts, con, sorted(years)) + if r.setting == "TOTAL" and r.specialty.strip().upper() not in ("TOTAL", "") + ] + + +def _impact_facts( + bib: _Bib, impacts: Sequence[Any], billing: Mapping[int, set[str]] +) -> list[Fact]: + from pfs.commenters import specialty_key + + out = [] + for r in impacts: + if r.impact_combined is None or specialty_key(r.specialty) not in billing.get( + r.rule_year, set() + ): + continue + if r.source == "fr": + cite = fr_page_cite(bib.store, r.item_key, r.page) + else: + url = "" + row = ( + bib.store._con() # noqa: SLF001 + .execute("SELECT url FROM items WHERE key = ?", (r.item_key,)) + .fetchone() + ) + if row: + url = row[0] or "" + cite = dataset_cite( + r.item_key, + f"CY{r.rule_year} PFS {r.vintage} rule specialty impact file", + url, + ) + out.append( + _draft( + "impact", + r.rule_year, + (), + f"CMS estimated the CY{r.rule_year} {r.vintage} rule's combined impact " + f"on allowed charges for {r.specialty} at {_pct(r.impact_combined)}.", + cite, + {"impact_combined": _pct(r.impact_combined), "specialty": r.specialty}, + ) + ) + return out + + +def _psps_cite(psps: Sequence[Any], year: int) -> Cite: + from pfs.psps import API, DATASETS + + past = [r for r in psps if r.year < year] + py = max((r.year for r in past), default=year - 1) + item = next((r.item_key for r in past if r.year == py), "") + url = API.format(id=DATASETS[py]) if py in DATASETS else "" + return dataset_cite( + item, f"Medicare Physician/Supplier Procedure Summary CY{py}", url + ) + + +def _money_facts( + year: int, money: Sequence[Any], psps: Sequence[Any], family: Any +) -> list[Fact]: + out: list[Fact] = [] + if not money: + return out + cite = _psps_cite(psps, year) + also = [rvu_cite(year - 1), rvu_cite(year)] + if money[0].new_codes: + out.append( + _draft( + "money", + year, + money[0].new_codes, + f"For CY{year}, the family gained new payment through " + f"{_join_and(money[0].new_codes)} ({money[0].delta_note}).", + rvu_cite(year), + {}, + ) + ) + ranked = [m for m in money if m.share >= MIN_SHARE and m.specialty != "NONE"] + for m in ranked[:MONEY_SPECIALTIES]: + svc = f"{'at least ' if m.lower_bound else ''}{m.services:,.0f} of the family's services" + suppressed = ( + " (CMS suppresses lines under 11 services)" if m.lower_bound else "" + ) + if m.delta_total is None: + change = "no final payment change is computed for those services" + else: + change = "the final payment change on those services was " + money_change( + m.delta_total, lower_bound=m.lower_bound + ) + if m.delta_pct is not None: + change += f" ({m.delta_pct:+.1%})" + values: dict[str, Any] = { + "services": round(m.services), + "share": f"{m.share:.1%}", + } + if m.delta_total is not None: + values["delta_total"] = round(abs(m.delta_total)) + if m.delta_pct is not None: + values["delta_pct"] = f"{m.delta_pct:+.1%}" + out.append( + _draft( + "money", + year, + (), + f"For CY{year}, {m.specialty} billed {svc}{suppressed} in the latest " + f"PSPS year before CY{year}, {m.share:.1%} of the family; {change}.", + cite, + values, + also, + ) + ) + if m.proposed_delta_total is not None: + out.append( + _draft( + "money", + year, + (), + f"For CY{year}, the proposed payment change on the same services " + f"for {m.specialty} was " + f"{money_change(m.proposed_delta_total, lower_bound=m.lower_bound)}.", + cite, + {"proposed_delta_total": round(abs(m.proposed_delta_total))}, + also, + ) + ) + return out + + +def _roster_cite(row: Any, year: int) -> Cite: + from pfs.seats import snapshot_url + + body = "RUC" if row.body == "RUC" else "CPT Editorial Panel" + url = snapshot_url(row.snapshot, row.source_url) if row.snapshot else row.source_url + label = f"AMA {body} roster {year}" + return Cite("dataset", label, url, row.item_key, locator=label) + + +def _seat_facts( + seats: Sequence[Any], years: Sequence[int], specialties: Mapping[int, set[str]] +) -> list[Fact]: + """RUC seats per specialty (R91 roster year), for the specialties of + *specialties*[rule year]; RUC seats with no mapped specialty (Primary + Care, Oncology) under their own labels; CPT Panel rows as categories.""" + from pfs.seats import seats_by_specialty + + ruc = [s for s in seats if s.body == "RUC"] + cpt = [s for s in seats if s.body == "CPT_PANEL"] + out: list[Fact] = [] + for year in sorted(set(years)): + ry, note = roster_year({s.year for s in ruc}, year) + if ry is not None: + rows = [s for s in ruc if s.year == ry] + by_spec = seats_by_specialty(rows, ry) + for spec in sorted(specialties.get(year, set()) & set(by_spec)): + perm, rot, _cpt, _holders, _keys = by_spec[spec] + first = next(s for s in rows if s.specialty == spec) + out.append( + _draft( + "seat", + year, + (), + f"On the {ry} RUC roster{note}, {spec} held {perm} permanent and " + f"{rot} rotating seats.", + _roster_cite(first, ry), + {"roster_year": ry, "specialty": spec}, + ) + ) + for s in rows: + if ( + not s.specialty + and s.holder_kind == "organization" + and s.seat_type in ("permanent", "rotating") + ): + out.append( + _draft( + "seat", + year, + (), + f"On the {ry} RUC roster, the {s.organization} is a " + f"{s.seat_type} seat.", + _roster_cite(s, ry), + {"roster_year": ry}, + ) + ) + cy, _cnote = roster_year({s.year for s in cpt}, year) + if cy is not None: + for s in (s for s in cpt if s.year == cy): + plural = "s" if s.n_seats != 1 else "" + out.append( + _draft( + "seat", + year, + (), + f"The {cy} CPT Editorial Panel roster lists {s.n_seats} seat" + f"{plural} for {s.organization}.", + _roster_cite(s, cy), + {"roster_year": cy, "n_seats": s.n_seats}, + ) + ) + return out + + +# ── assembly ──────────────────────────────────────────────────────── + + +@dataclass +class _Assembly: + facts: list[Fact] + years: list[int] + rounds: list[RoundRow] + payment: list[Any] + psps: list[Any] + seats: list[Any] + money: dict[int, list[Any]] + impacts: list[Any] + billing: dict[int, set[str]] + + +def _assemble( + con: Any, store: Any, family: Any, excerpts: Sequence[Excerpt] = () +) -> _Assembly: + from pfs.stakes import billing_share, money_by_specialty, read_becomes_payable + + bib = _Bib(store) + rounds = _rows(read_rounds, con, family.key) + drafts: list[Fact] = [ + *_origin_facts(con, bib, family), + *_guideline_facts(con, bib, family), + *_event_facts(con, bib, family), + *_link_facts(bib, family), + *_round_facts(bib, rounds), + *_pe_facts(bib, rounds), + *_cms_facts(con, bib, family), + *_stance_facts(con, family), + ] + # rule years the family's own history touches (a CPT edition year is not one) + years = sorted( + { + f.year + for f in drafts + if f.year + and not f.note + and f.kind in ("round", "event", "link", "stance_split") + and f.values.get("event_kind") != "cpt_edition" + } + ) + payment = _payment_rows(con, family) + drafts += _payment_facts(payment) + codes = [*family.codes, *(ln.target for ln in family.links)] + psps = _rows(read_psps, con, codes) + exposures = _rows(read_becomes_payable, con, family.codes) + final_years = {r.year for r in payment if not r.proposed} + money: dict[int, list[Any]] = {} + billing: dict[int, set[str]] = {} + for y in years: + billing[y] = { + s for s, share in billing_share(psps, year=y).items() if share >= MIN_SHARE + } + if y in final_years and y - 1 in final_years: + money[y] = money_by_specialty( + payment, psps, year=y, links=family.links, exposures=exposures + ) + drafts += _money_facts(y, money[y], psps, family) + impacts = _impact_rows(con, years) + drafts += _impact_facts(bib, impacts, billing) + seats = _rows(read_seats, con) + stance_years = {f.year for f in drafts if f.kind == "stance_split" and f.year} + round_years = {f.year for f in drafts if f.kind == "round" and f.year} + link_years = {ln.since for ln in family.links if ln.since} + # per rule year: the specialties billing the family and those of the + # commenters on that year's docket + docket_year = _docket_rule_years(store) + seat_specs: dict[int, set[str]] = {} + for c in _rows(read_commenters, con, family=family.key): + if c.specialty and c.specialty != "NONE" and docket_year.get(c.docket): + seat_specs.setdefault(docket_year[c.docket], set()).add(c.specialty) + for y, specs in billing.items(): + seat_specs.setdefault(y, set()).update(specs) + drafts += _seat_facts( + seats, sorted(stance_years | round_years | link_years), seat_specs + ) + drafts += [_draft("finding", None, (), e.text, e.cite, {}) for e in excerpts] + seen: set[tuple] = set() + unique = [] + for f in sorted(drafts, key=_order_key): + key = (f.kind, f.year, f.text) + if key in seen: + continue + seen.add(key) + unique.append(f) + facts = [replace(f, id=f"F{i}") for i, f in enumerate(unique, 1)] + return _Assembly( + facts, years, rounds, payment, psps, seats, money, impacts, billing + ) + + +def collect_facts(con: Any, store: Any, family: Any) -> list[Fact]: + """Every fact of *family* from the stored rows, ids ``F1…`` in (year, + kind, code) order; each carries a :class:`Cite` with a URL or a + locator.""" + return _assemble(con, store, family).facts + + +# ── coverage: what the sources do not yet reach (computed) ────────── + + +def _spans(years: Sequence[int]) -> str: + ys = sorted(set(years)) + out: list[str] = [] + i = 0 + while i < len(ys): + j = i + while j + 1 < len(ys) and ys[j + 1] == ys[j] + 1: + j += 1 + out.append(f"{ys[i]}–{ys[j]}" if j > i else str(ys[i])) + i = j + 1 + return ", ".join(out) + + +def _seat_log(con: Any) -> tuple[dict[str, set[int]], list[str]]: + """``(body -> gap years, note lines)`` from ``cms.ingest_log`` (module + ``pfs.seats``): gap rows say ``# ()``, note rows + ``# note: ``; repeats are read once.""" + try: + rows = con.execute( + "SELECT rule_id, source_file FROM cms.ingest_log " + "WHERE module = 'pfs.seats' AND rule_id IN ('gap', 'note')" + ).fetchall() + except Exception as exc: # noqa: BLE001 + if is_missing_table_error(exc): + return {}, [] + raise + gaps: dict[str, set[int]] = {} + notes: set[tuple[int, str]] = set() + for rule, src in rows: + m = re.search(r"#(\d{4})\s*(.*)$", src or "") + if m is None: + continue + body = "CPT_PANEL" if "cpt-editorial-panel" in src else "RUC" + if rule == "gap": + gaps.setdefault(body, set()).add(int(m.group(1))) + elif m.group(2).startswith("note:"): + notes.add((int(m.group(1)), m.group(2)[5:].strip())) + return gaps, [f"{y}: {t}" for y, t in sorted(notes)] + + +def _seat_coverage(con: Any) -> list[str]: + seats = _rows(read_seats, con) + if not seats: + return ["RUC/CPT Panel seat data not captured."] + gaps, notes = _seat_log(con) + parts = [] + for body, name in (("RUC", "RUC rosters"), ("CPT_PANEL", "CPT Panel rosters")): + have = {s.year for s in seats if s.body == body} + if not have: + parts.append(f"{name} not captured") + continue + text = f"{name} captured {_spans(sorted(have))}" + missing = sorted(gaps.get(body, set()) - have) + if missing: + text += f" ({_spans(missing)} not captured)" + parts.append(text) + out = ["; ".join(parts) + "."] + if notes: + out.append("RUC roster notes: " + "; ".join(notes) + ".") + return out + + +def _earliest_rule_year(store: Any) -> int | None: + from pfs.rounds import rule_items + + years = [ + rule_year_of(it["title"], it["date_published"]) for it in rule_items(store, []) + ] + return min(years) if years else None + + +def _governance_keys(store: Any) -> list[str]: + return [ + r[0] + for r in store._con() # noqa: SLF001 + .execute( + "SELECT DISTINCT i.key FROM items i JOIN item_tags it ON it.item_id = i.id " + "JOIN tags t ON t.id = it.tag_id WHERE t.name = 'source:governance-lit' " + "ORDER BY i.key" + ) + .fetchall() + ] + + +def _docket_rule_years(store: Any) -> dict[str, int]: + from pfs.stance import docket_rule_year + + return {d.id: docket_rule_year(d.comment_end_date) for d in store.dockets()} + + +def coverage( + con: Any, store: Any, family: Any, *, years: Sequence[int] | None = None +) -> list[str]: + """The family's gap notes, each computed from what is on file: the + earliest captured PFS rule, RVU year and comment docket, years with no + conversion factor, roster capture (span, gaps, notes), governance + literature, unmatched impact rows, unclassified dockets and the + commenter-count method.""" + from pfs.commenters import specialty_key + from pfs.valuation import skipped_years + + out: list[str] = [] + first = _earliest_rule_year(store) + out.append( + f"Federal Register PFS rules before CY{first} not yet captured." + if first + else "Federal Register PFS rules not yet captured." + ) + try: + lo = con.execute("SELECT min(year) FROM pfs.rvu").fetchone()[0] + except Exception as exc: # noqa: BLE001 + if not is_missing_table_error(exc): + raise + lo = None + out.append( + f"RVU files before {lo} not yet loaded." if lo else "RVU files not yet loaded." + ) + rule_years = _docket_rule_years(store) + dockets = [ + r + for r in _rows(read_reaction, con, family.key) + if r.period_kind == "docket" and r.n_total > 0 and r.n_items > 0 + ] + docket_years = [rule_years.get(r.period) or r.year + 1 for r in dockets] + if docket_years: + out.append( + f"Public comment dockets before the CY{min(docket_years)} rule not yet " + "captured." + ) + if lo: + skipped = skipped_years(con, family.codes) + if skipped: + out.append( + f"No conversion factor on file for {', '.join(map(str, skipped))}; " + "payment not computed." + ) + out += _seat_coverage(con) + if not _governance_keys(store): + out.append("Governance literature not yet ingested.") + # the impact rows of the dossier's rule years (*years*; every year when + # not given), one name per specialty however each table spells it + if years is None: + years = sorted({r.rule_year for r in _rows(read_specialty_impacts, con)}) + psps = _rows(read_psps, con, family.codes) + vocab = _specialty_vocab(con, {specialty_key(r.specialty) for r in psps}) + names: dict[str, str] = {} + for r in _impact_rows(con, years): + if specialty_key(r.specialty) not in vocab: + names.setdefault(specialty_key(r.specialty), r.specialty) + unmatched = [names[k] for k in sorted(names)] + if unmatched: + out.append( + f"Specialty impact rows not matched to a specialty: {', '.join(unmatched)}." + ) + with_people = {c.docket for c in _rows(read_commenters, con, family=family.key)} + with_people |= {r.period for r in dockets} + classified = sorted(r.period for r in _classified(con, family)) + if with_people: + out.append( + f"Comment stance classified for {len(classified)} of {len(with_people)} " + f"dockets with family commenters ({', '.join(classified) or 'none'})." + ) + out.append( + "Commenters are counted only when their comment names a family code or " + f"one of its {len(family.pair_phrases)} curated phrases; other comments " + "that mention the family await review." + ) + return out + + +# ── timeline ──────────────────────────────────────────────────────── + +_TIMELINE_ORDER = ( + "origin", + "formation", + "cpt_edition", + "valuation", + "created", + "deleted", + "cpt_panel", + "disappeared", + "appeared", + "replaced_by", + "replaces", + "crosswalk", + "revalued", + "status_change", + "descriptor_change", + "telehealth_list", + "misvalued", + "bundled", + "link", + "comments", +) +_TL_RANK = {k: i for i, k in enumerate(_TIMELINE_ORDER)} +_NOT_RULE_EVENTS = frozenset({"formation", "cpt_edition"}) + + +def _tl_kind(f: Fact) -> str | None: + if f.note or f.year is None: + return None + if f.kind == "event": + return str(f.values.get("event_kind")) + if f.kind == "round": + return "valuation" + if f.kind == "link": + return f"link:{f.codes[0]}" + if f.kind in ("origin", "formation"): + return f.kind + return None + + +def _tl_rank(kind: str) -> int: + return _TL_RANK.get(kind.split(":")[0], len(_TL_RANK)) + + +def _tags(ids: Sequence[str]) -> str: + return "".join(f"[{i}]" for i in ids) + + +def _with_tags(text: str, ids: Sequence[str]) -> str: + first = split_sentences(text)[0] if text else "" + return f"{first.rstrip('.').rstrip()} {_tags(ids)}." + + +def template_event_line(e: TimelineEvent, facts: Mapping[str, Fact]) -> str: + """The deterministic line for one timeline event, built from its facts' + own text so it passes the citation check by construction.""" + mine = [facts[i] for i in e.fact_ids] + if not mine: + ids = list(e.cms_summary_fact_ids or e.stance_fact_ids)[:1] + return _with_tags(facts[ids[0]].text, ids) + if e.kind in _EVENT_PLURAL and len(e.codes) > 1: + head = _EVENT_PLURAL[e.kind].format(codes=compact(e.codes), year=e.year) + return f"{head} {_tags(e.fact_ids)}." + if e.kind == "valuation": + finals = [f for f in mine if "CMS finalized" in f.text] + proposed = [f for f in mine if "CMS proposed" in f.text] + for group, verb in ((finals, "finalized"), (proposed, "proposed")): + if group: + codes = sorted({c for f in group for c in f.codes}) + return ( + f"For CY{e.year}, CMS {verb} work RVUs for {compact(codes)} " + f"{_tags([f.id for f in group])}." + ) + # a rule's own words first (a book paraphrase can lack a subject) + lead = next((f for f in mine if f.cite.kind == "fr_para"), mine[0]) + return _with_tags(lead.text, [lead.id]) + + +def timeline(facts: Sequence[Fact]) -> list[TimelineEvent]: + """Facts grouped by (year, kind): origins and formation with a year, CPT + edition changes, valuation rounds, lineage events and links; our stance + counts and CMS's summaries attach to the event of their year they speak + to (a year with only comments gets a ``comments`` event). Each event's + ``what_changed`` is its template line.""" + groups: dict[tuple[int, str], list[Fact]] = {} + for f in facts: + k = _tl_kind(f) + if k is not None: + groups.setdefault((f.year, k), []).append(f) # type: ignore[arg-type] + stance: dict[tuple[int, str], list[str]] = {} + cms: dict[tuple[int, str], list[str]] = {} + + def target(year: int, prefer: Sequence[str]) -> tuple[int, str]: + for k in prefer: + if (year, k) in groups: + return (year, k) + # a Panel meeting, a codebook edition or an origin is no rule event: + # comments on a rule never attach to one unless asked for by name + same = sorted( + (k for y, k in groups if y == year and k not in _NOT_RULE_EVENTS), + key=_tl_rank, + ) + if same: + return (year, same[0]) + groups[(year, "comments")] = [] + return (year, "comments") + + for f in facts: + if f.kind == "stance_split" and f.year: + slug = str(f.values.get("event_key", "")).split(":")[-1] + prefer = { + "valuation": ["valuation"], + "coding": ["deleted", "formation", "cpt_panel", "cpt_edition"], + "telehealth": ["telehealth_list"], + "other": ["valuation"], + "": ["valuation"], + }.get(slug, [f"link:{slug}"]) + stance.setdefault(target(f.year, prefer), []).append(f.id) + for f in facts: + if f.kind == "cms_summary" and f.year: + prefer = [ + k + for (y, k), fs in sorted( + groups.items(), key=lambda kv: _tl_rank(kv[0][1]) + ) + if y == f.year + and k not in _NOT_RULE_EVENTS + and set(f.codes) & {c for g in fs for c in g.codes} + ] + ["valuation"] + prefer += sorted( + k for y, k in groups if y == f.year and k.startswith("link:") + ) + cms.setdefault(target(f.year, prefer), []).append(f.id) + by_id = {f.id: f for f in facts} + out = [] + for year, kind in sorted(groups, key=lambda yk: (yk[0], _tl_rank(yk[1]), yk[1])): + fs = groups[(year, kind)] + e = TimelineEvent( + year=year, + kind=kind, + codes=tuple(sorted({c for f in fs for c in f.codes})), + what_changed="", + fact_ids=tuple(f.id for f in fs), + stance_fact_ids=tuple(stance.get((year, kind), ())), + cms_summary_fact_ids=tuple(cms.get((year, kind), ())), + ) + out.append(replace(e, what_changed=template_event_line(e, by_id))) + return out + + +# ── prose: model lines behind the citation check ──────────────────── + +PROSE_SCHEMA: dict = { + "type": "object", + "required": ["text"], + "properties": {"text": {"type": "string", "maxLength": 1500}}, +} +_RULES = ( + "Use only the numbered facts given, in their own words: every word you " + "write that carries meaning must come from a fact you cite. End every " + "sentence with the tags of the facts it uses, written like [F12] or " + "[F3][F7]. Copy every number, code and year exactly as a cited fact " + "writes it; never write a number or code the cited facts do not carry, " + "nor a range of codes that spans one they do not name. Keep proposed " + "values apart from final " + "values (a proposed value is never what CMS finalized). Keep CMS's own " + 'characterization of commenters ("CMS reported ...") apart from our ' + 'classified counts ("we classified ..."). Neutral, factual tone: no ' + "judgment words, no speculation, no advice. Return JSON " + '{"text": "..."}.' +) +SUMMARY_SYSTEM = ( + "You write the summary paragraph of a dossier on a Medicare code family, " + "at most 5 sentences, from numbered facts. " + _RULES +) +EVENT_SYSTEM = ( + "You write ONE sentence saying what changed in one event of a Medicare " + "code family's history, from numbered facts. " + _RULES +) +_PROSE_KINDS = frozenset( + {"origin", "formation", "event", "round", "cms_summary", "stance_split", "link"} +) +_SUMMARY_FACTS = 80 + + +def _prose_facts(facts: Sequence[Fact]) -> list[Fact]: + """What the model may read: reviewed facts of the narrative kinds (no + flagged paraphrase, no payment cell, no quote).""" + return [f for f in facts if not f.note and f.kind in _PROSE_KINDS] + + +def _fact_lines(facts: Sequence[Fact]) -> str: + return "\n".join(f"[{f.id}] {f.text}" for f in facts) + + +def _summary_input(facts: Sequence[Fact]) -> list[Fact]: + rank = { + "link": 0, + "formation": 1, + "round": 2, + "stance_split": 3, + "cms_summary": 4, + "origin": 5, + "event": 6, + } + pool = sorted( + _prose_facts(facts), key=lambda f: (rank.get(f.kind, 9), -(f.year or 0)) + ) + picked = {f.id for f in pool[:_SUMMARY_FACTS]} + return [f for f in facts if f.id in picked] + + +def _event_input(e: TimelineEvent, by_id: Mapping[str, Fact]) -> list[Fact]: + ids = [*e.fact_ids, *e.stance_fact_ids, *e.cms_summary_fact_ids] + return [by_id[i] for i in ids if not by_id[i].note] + + +def _problems(text: str, allowed: Mapping[str, Fact], max_sentences: int) -> list[str]: + if not text.strip(): + return ["empty: no text"] + found = check_prose(text, allowed) + grounding_problems(text, allowed) + out = [f"{p.kind}: {p.sentence} ({p.detail})" for p in found] + n = len(split_sentences(text)) + if n > max_sentences: + out.append(f"too long: {n} sentences, at most {max_sentences}") + return out + + +def _ask_checked( + ask: Any, system: str, user: str, allowed: Mapping[str, Fact], max_sentences: int +) -> dict | None: + """One model answer that passes the check, after at most one retry with + the problems listed; ``None`` when both fail.""" + prompt = user + for _attempt in range(2): + out = ask(system, prompt, PROSE_SCHEMA) + text = out.get("text", "") if isinstance(out, dict) else "" + problems = _problems(text, allowed, max_sentences) + if not problems: + return {"text": " ".join(text.split())} + prompt = ( + f"{user}\n\nProblems with your previous answer (fix every one):\n" + + "\n".join(f"- {p}" for p in problems) + ) + return None + + +def template_summary(facts: Sequence[Fact], events: Sequence[TimelineEvent]) -> str: + """At most five template lines: the newest and the earliest finalized + valuation, the newest deletion and formation, and the links, in time + order.""" + by_id = {f.id: f for f in facts} + picked: list[TimelineEvent] = [] + vals = [e for e in events if e.kind == "valuation"] + if vals: + picked += [vals[-1]] + ([vals[0]] if len(vals) > 1 else []) + for kind in ("deleted", "formation"): + same = [e for e in events if e.kind == kind] + if same: + picked.append(same[-1]) + picked += [e for e in events if e.kind.startswith("link:")] + if not picked: + picked = list(events[:5]) + chosen = sorted(dict.fromkeys(picked[:5]), key=lambda e: (e.year, _tl_rank(e.kind))) + return " ".join(template_event_line(e, by_id) for e in chosen) + + +def write_prose( + facts: Sequence[Fact], + events: Sequence[TimelineEvent], + ask: Any | None, + *, + log: RunLog | None = None, + replay_model: str | None = None, + limit: int = 0, + fallbacks: list[str] | None = None, +) -> tuple[str, dict[int, str], str, bool]: + """The summary (at most five sentences) and one line per timeline event. + The model (*ask*, a ``JsonExtractor``) drafts each from the facts with + ``[F#]`` tags; ``check_prose`` and ``grounding_problems`` check every + sentence (citations and numbers; words, codes and the CMS-vs-ours + attribution), one retry lists the problems, and a draft still failing + (or no model) is replaced by the template line. Flagged paraphrases, + payment cells and quotes are never given to the model. With a ledger *log* each unit is asked once (resumable, + *limit* caps new units); without *ask* the ledger recorded for + *replay_model* is replayed. Returns ``(summary, lines by event index, + extractor, check_passed)``; nothing unchecked is ever returned. A + *fallbacks* list receives the units that fell back to template copy + ("summary", "CY2023 valuation").""" + by_id = {f.id: f for f in facts} + model = getattr(ask, "model", None) if ask is not None else replay_model + units: list[tuple[str, str, str, dict[str, Fact], int, str]] = [] + s_in = _summary_input(facts) + units.append( + ( + "summary", + SUMMARY_SYSTEM, + f"Write the summary from these facts.\nFacts:\n{_fact_lines(s_in)}", + {f.id: f for f in s_in}, + 5, + template_summary(facts, events), + ) + ) + for i, e in enumerate(events): + e_in = _event_input(e, by_id) + units.append( + ( + f"event:{e.year}:{e.kind}", + EVENT_SYSTEM, + f"Event: CY{e.year}, {e.kind}.\nFacts:\n{_fact_lines(e_in)}", + {f.id: f for f in e_in}, + 2, + template_event_line(e, by_id), + ) + ) + texts: list[str] = [] + used_model = used_template = False + calls = 0 + for unit, system, user, allowed, max_s, fallback in units: + out: dict | None = None + if model is not None and allowed: + h = input_hash(system, user) + entry = log.get(unit, h, model, PROSE_PROMPT_VERSION) if log else None + if entry is not None: + out = entry.output + elif ask is not None and not (limit and calls >= limit): + calls += 1 + out = _ask_checked(ask, system, user, allowed, max_s) + if log is not None: + log.put(unit, h, model, PROSE_PROMPT_VERSION, out) + # a recorded answer is re-checked: nothing unchecked is returned + if out is not None and not _problems(out["text"], allowed, max_s): + texts.append(out["text"]) + used_model = True + else: + texts.append(fallback) + used_template = True + if fallbacks is not None: + fallbacks.append( + "summary" + if unit == "summary" + else "CY" + unit[6:].replace(":", " ", 1) + ) + if used_model and used_template: + extractor = f"model:{model}+template" + elif used_model: + extractor = f"model:{model}" + else: + extractor = "template" + ok = all( + not check_prose(t, by_id) and not grounding_problems(t, by_id) for t in texts + ) + return texts[0], dict(enumerate(texts[1:])), extractor, ok + + +# ── stakeholders ──────────────────────────────────────────────────── + + +def _unit_dict(u: Any) -> dict: + share = u.share + return { + "org_type": u.org_type, + "specialty": u.specialty, + "names": list(u.names), + "n_commenters": u.n_commenters, + "stance": dict(u.stance), + "expected": u.expected.stance, + "expected_reason": u.expected.reason, + "share": share, + "share_text": ("<0.1%" if 0 < share < 0.0005 else f"{share:.1%}") + if share + else "", + "delta_total": u.delta_total, + "delta_lower_bound": u.delta_lower_bound, + "delta_text": money_change(u.delta_total, lower_bound=u.delta_lower_bound), + } + + +def _stakeholders(con: Any, family: Any, a: _Assembly) -> list[dict]: + """One panel per classified (docket, event): org type x specialty units + with names as posted (R87), stance counts, the expected stance and its + reason, billing share and money; RUC seats once per specialty (R91 roster + year). The new-payment expectation goes with the link event that brought + the new payment, not with the others.""" + from pfs.seats import seats_by_specialty + from pfs.stakes import stakeholder_units + + ruc = [s for s in a.seats if s.body == "RUC"] + out: list[dict] = [] + for r in _classified(con, family): + events = json.loads(r.events_json or "{}") + commenters = [ + c + for c in _rows(read_commenters, con, family=family.key) + if c.docket == r.period + ] + stances = _rows(read_stances, con, family.key, r.period) + acc = stance_accuracy_line(_eval(r)) + for key in events: + year = _event_year(key) or r.year + slug = key.split(":")[-1] + money = a.money.get(year, []) + new_here = any( + ln.target == slug and ln.since == year for ln in family.links + ) + if not new_here: + money = [ + replace(m, new_payment=False, new_codes=(), delta_note="") + for m in money + ] + units = stakeholder_units( + commenters, stances, money, event_key=key, year=year + ) + ry, note = roster_year({s.year for s in ruc}, year) + by_spec = ( + seats_by_specialty([s for s in ruc if s.year == ry], ry) if ry else {} + ) + seats = { + spec: { + "ruc_permanent": v[0], + "ruc_rotating": v[1], + "cpt": v[2], + "holders": list(v[3]), + "item_keys": list(v[4]), + } + for spec, v in by_spec.items() + if spec in {u.specialty for u in units} + } + out.append( + { + "docket": r.period, + "rule_year": year, + "event_key": key, + "event_text": event_label(slug), + "accuracy": acc, + "roster_year": ry, + "roster_note": note.strip(" ()"), + "units": [_unit_dict(u) for u in units], + "seats": seats, + } + ) + return out + + +def stakeholder_lines(d: Dossier) -> list[str]: + """The stakeholder panels as plain text (the CLI and the report).""" + out: list[str] = [] + for p in d.stakeholders: + out.append( + f"stakeholders (CY{p['rule_year']}, {p['event_key']} — {p['event_text']}; " + f"RUC roster {p['roster_year'] or 'not captured'})" + ) + out.append(f" {p['accuracy']}") + out.append( + " org type | specialty | commenters | stance | expected (reason) | " + "billing share | payment change | RUC seats" + ) + for u in p["units"]: + stance = ", ".join(f"{k} {v}" for k, v in u["stance"].items()) + seat = p["seats"].get(u["specialty"]) + seat_text = ( + f"{seat['ruc_permanent']} permanent, {seat['ruc_rotating']} rotating" + if seat + else "" + ) + out.append( + f" {u['org_type']} | {u['specialty']} | {'; '.join(u['names'])} " + f"({u['n_commenters']}) | {stance} | {u['expected']} " + f"({u['expected_reason']}) | {u['share_text']} | {u['delta_text']} | " + f"{seat_text}" + ) + return out + + +# ── the dossier ───────────────────────────────────────────────────── + + +def _status(family: Any, payment: Sequence[Any]) -> str: + active = [m.code for m in family.members if m.until is None] + deleted = [m for m in family.members if m.until is not None] + text = f"{len(active)} active codes, {len(deleted)} deleted" + if deleted: + last = max(m.until for m in deleted) + text += f" (last payable CY{last})" + if family.links: + text += "; linked: " + ", ".join( + f"{ln.target} from CY{ln.since}" for ln in family.links if ln.since + ) + return text + + +def _years_active(facts: Sequence[Fact], payment: Sequence[Any]) -> str: + years = [f.year for f in facts if f.year and not f.note] + [r.year for r in payment] + return f"CY{min(years)}–CY{max(years)}" if years else "" + + +def _sources( + facts: Sequence[Fact], excerpts: Sequence[Excerpt] +) -> dict[str, list[dict]]: + seen: set[tuple] = set() + out: dict[str, list[dict]] = {} + for c in [x for f in facts for x in (f.cite, *f.also)] + [e.cite for e in excerpts]: + key = (c.kind, c.label, c.url) + if key in seen: + continue + seen.add(key) + out.setdefault(c.kind, []).append(asdict(c)) + return out + + +def build_dossier( + con: Any, + store: Any, + family: Any, + *, + ask: Any | None = None, + excerpts: Sequence[Excerpt] = (), + log: RunLog | None = None, + replay_model: str | None = None, + limit: int = 0, +) -> Dossier: + """The whole dossier of *family*: facts, timeline, valuation rounds, + payment, utilization, stakeholders, governance excerpts, sources, gaps and + the checked prose (see ``write_prose`` for *ask*/*log*/*replay_model*/ + *limit*).""" + from pfs.utilization import read_series + + a = _assemble(con, store, family, excerpts) + facts = a.facts + by_id = {f.id: f for f in facts} + events = timeline(facts) + fallbacks: list[str] = [] + summary, lines, extractor, ok = write_prose( + facts, + events, + ask, + log=log, + replay_model=replay_model, + limit=limit, + fallbacks=fallbacks, + ) + final_events = [replace(e, what_changed=lines[i]) for i, e in enumerate(events)] + codes = [*family.codes, *(ln.target for ln in family.links)] + util = [asdict(r) for r in _rows(read_series, con, codes)] + classified = _classified(con, family) + acc = "" + if classified: + ev = _eval(classified[-1]) + acc = stance_accuracy_line(ev) + (_in_sample_line(ev) if ev else "") + return Dossier( + family=family.key, + name=family.name, + codes=tuple(family.codes), + status=_status(family, a.payment), + years_active=_years_active(facts, a.payment), + summary=summary, + timeline=final_events, + rounds=_round_dicts(_Bib(store), a.rounds), + payment=[_payment_dict(r) for r in a.payment], + utilization=util, + stakeholders=_stakeholders(con, family, a), + governance=list(excerpts), + sources=_sources(facts, excerpts), + gaps=coverage(con, store, family, years=a.years), + facts=by_id, + built_at=_dt.datetime.now(_dt.UTC) + .replace(tzinfo=None) + .isoformat(timespec="seconds"), + check_passed=ok, + extractor=extractor, + review=[{"fact_id": f.id, "reason": f.note} for f in facts if f.note], + fallbacks=fallbacks, + stance_accuracy=acc, + ) + + +# ── governance excerpts ───────────────────────────────────────────── + +GOVERNANCE_QUERIES = ( + "{name} valuation", + "RUC recommendations accepted by CMS", + "RUC survey data and time estimates", + "specialty representation on the RUC and prices", + "international physician fee setting governance", +) +EXCERPT_CHARS = 300 + + +def _excerpt(text: str) -> str: + text = " ".join((text or "").split()) + if len(text) <= EXCERPT_CHARS: + return text + return text[: EXCERPT_CHARS - 1].rsplit(" ", 1)[0] + "…" + + +def governance_excerpts( + cfg: Any, pool: Any, store: Any, family_name: str, *, k: int = 6 +) -> list[Excerpt]: + """Up to *k* passages of the governance literature (bib items tagged + ``source:governance-lit``) that bear on the family and on RUC/fee-setting + governance, each at most 300 characters and cited as a ``study`` (with + its page when the chunk has one). ``[]`` when none is ingested.""" + from llm import search as llm_search + + keys = _governance_keys(store) + if not keys: + return [] + out: list[Excerpt] = [] + seen: set[str] = set() + for q in GOVERNANCE_QUERIES: + hits = llm_search.search( + q.format(name=family_name), + cfg=cfg, + pool=pool, + collection="corpus", + item_keys=keys, + limit=3, + ) + for h in hits: + label = h.get("label") or h.get("item_key", "") + if label in seen: + continue + seen.add(label) + page = str(h.get("page") or "") + out.append( + Excerpt( + _excerpt(h.get("text") or h.get("snippet", "")), + Cite( + "study", + label, + h.get("url", ""), + h.get("item_key", ""), + 0, + int(page) if page.isdigit() else 0, + label, + ), + ) + ) + return out[:k] + + +# ── storage (pfs.dossier; DDL in pfs.codetables) ──────────────────── + + +def write_dossier(con: Any, d: Dossier) -> int: + """Replace the family's stored dossier.""" + ensure_tables(con) + con.execute("DELETE FROM pfs.dossier WHERE family = ?", [d.family]) + con.execute( + "INSERT INTO pfs.dossier VALUES (?, ?, ?, ?, ?, ?)", + [ + d.family, + _dt.datetime.fromisoformat(d.built_at), + d.version, + d.to_json(), + d.check_passed, + d.extractor, + ], + ) + return 1 + + +def read_dossier(con: Any, family: str) -> Dossier | None: + try: + row = con.execute( + "SELECT json FROM pfs.dossier WHERE family = ?", [family] + ).fetchone() + except Exception as exc: # noqa: BLE001 + if is_missing_table_error(exc): + return None + raise + return Dossier.from_json(row[0]) if row else None + + +def dossier_families(con: Any) -> tuple[str, ...]: + """Families with a stored dossier; ``()`` before the table exists.""" + try: + rows = con.execute("SELECT family FROM pfs.dossier ORDER BY family").fetchall() + except Exception as exc: # noqa: BLE001 + if is_missing_table_error(exc): + return () + raise + return tuple(r[0] for r in rows) diff --git a/tests/cli/test_pfs_cli.py b/tests/cli/test_pfs_cli.py index 6b49b96..7f9dc16 100644 --- a/tests/cli/test_pfs_cli.py +++ b/tests/cli/test_pfs_cli.py @@ -3591,3 +3591,139 @@ class TestSeats: def test_seat_root_sits_beside_the_primary_database(): assert str(pfs_cli._seat_root()).endswith("ama/rosters") + + +# ── stack pfs dossier (task 13) ────────────────────────────────────── + +from tests.pfs.home_visits_fixture import FakeAsk, home # noqa: E402 + + +def _echo_prose(system, user): + import re as _re + + m = _re.search(r"^\[(F\d+)\] (.+)$", user, _re.M) + return {"text": f"{m.group(2).rstrip('.')} [{m.group(1)}]."} + + +class TestDossier: + @pytest.fixture + def env(self, monkeypatch, tmp_path): + with home(tmp_path / "home") as parts: + yield self._env(parts, monkeypatch, tmp_path) + + def _env(self, parts, monkeypatch, tmp_path): + con, store, family, _ask = parts + published: list[bool] = [] + + class _Batch: + def __enter__(self): + return con + + def __exit__(self, *a): + return False + + monkeypatch.setattr(pfs_cli, "_batch", lambda: _Batch()) + monkeypatch.setattr(pfs_cli, "_read", lambda: con.cursor()) + monkeypatch.setattr(pfs_cli, "_store", lambda: store) + monkeypatch.setattr(pfs_cli, "_publish", lambda: published.append(True)) + monkeypatch.setattr(pfs_cli, "_model_name", lambda large=False: "fake-14b") + monkeypatch.setattr( + pfs_cli, "ledger_path", lambda task, fam: tmp_path / f"{task}-{fam}.jsonl" + ) + excerpts: list[tuple] = [] + monkeypatch.setattr( + pfs_cli, "_excerpts", lambda store, name: excerpts.append(name) or [] + ) + return SimpleNamespace(con=con, published=published, excerpts=excerpts) + + def test_no_llm_prints_facts_gaps_and_the_check(self, env): + res = runner.invoke( + app, ["pfs", "dossier", "--family", "HOME-VISITS", "--no-llm"] + ) + assert res.exit_code == 0, res.output + assert "HOME-VISITS:" in res.output and " facts (" in res.output + assert ( + "gap: Federal Register PFS rules before CY2002 not yet captured." + in res.output + ) + assert "check: passed; prose template" in res.output + assert "timeline years: 2008" in res.output + assert "stakeholders (CY2023, HOME-VISITS:2023:valuation" in res.output + assert env.published == [] and env.excerpts == [] + from pfs.dossier import dossier_families + + assert dossier_families(env.con) == () + + def test_write_stores_the_dossier_and_publishes(self, env): + res = runner.invoke( + app, ["pfs", "dossier", "--family", "home-visits", "--no-llm", "--write"] + ) + assert res.exit_code == 0, res.output + from pfs.dossier import read_dossier + + d = read_dossier(env.con, "HOME-VISITS") + assert d is not None and d.check_passed + assert "wrote dossier HOME-VISITS" in res.output + assert env.published == [True] + + def test_all_builds_every_curated_family(self, env): + res = runner.invoke(app, ["pfs", "dossier", "--all", "--no-llm"]) + assert res.exit_code == 0, res.output + assert "HOME-VISITS:" in res.output + + def test_needs_a_family_or_all(self, env): + res = runner.invoke(app, ["pfs", "dossier"]) + assert res.exit_code != 0 and "--family" in res.output + res = runner.invoke(app, ["pfs", "dossier", "--family", "NOPE", "--no-llm"]) + assert res.exit_code != 0 and "unknown curated family" in res.output + + def test_model_prose_through_the_ledger(self, env, monkeypatch, tmp_path): + ask = FakeAsk(default=_echo_prose) + monkeypatch.setattr(pfs_cli, "_asker", lambda large=False: ask) + res = runner.invoke( + app, ["pfs", "dossier", "--family", "HOME-VISITS", "--limit", "2"] + ) + assert res.exit_code == 0, res.output + assert len(ask.calls) == 2 + assert "prose model:fake-14b+template" in res.output + assert "template fallback:" in res.output + assert env.excerpts == ["Home or Residence Services"] + res = runner.invoke(app, ["pfs", "dossier", "--family", "HOME-VISITS"]) + assert res.exit_code == 0, res.output + assert "check: passed; prose model:fake-14b" in res.output + # --no-llm replays the finished ledger: no new calls, same prose + n = len(ask.calls) + res = runner.invoke( + app, ["pfs", "dossier", "--family", "HOME-VISITS", "--no-llm"] + ) + assert "prose model:fake-14b" in res.output and len(ask.calls) == n + assert (tmp_path / "prose-HOME-VISITS.jsonl").exists() + + def test_dry_run_makes_no_calls_and_no_writes(self, env, monkeypatch): + monkeypatch.setattr( + pfs_cli, "_asker", lambda large=False: pytest.fail("no model on a dry run") + ) + res = runner.invoke( + app, ["pfs", "dossier", "--family", "HOME-VISITS", "--dry-run", "--write"] + ) + assert res.exit_code == 0, res.output + assert "model calls a run would make:" in res.output + assert env.published == [] + + +def test_dossier_excerpts_use_the_llm_pool(monkeypatch): + from llm import config as llm_config + from llm import pool as llm_pool + + calls = [] + monkeypatch.setattr(llm_config, "load", lambda: "CFG") + monkeypatch.setattr( + llm_pool.HostPool, "from_config", classmethod(lambda c, cfg: "POOL") + ) + monkeypatch.setattr( + pfs_cli, + "governance_excerpts", + lambda cfg, pool, store, name: calls.append((cfg, pool, store, name)) or [], + ) + assert pfs_cli._excerpts("STORE", "Home or Residence Services") == [] + assert calls == [("CFG", "POOL", "STORE", "Home or Residence Services")] diff --git a/tests/llm/test_lineage.py b/tests/llm/test_lineage.py index 90e8296..ea64238 100644 --- a/tests/llm/test_lineage.py +++ b/tests/llm/test_lineage.py @@ -244,6 +244,13 @@ class TestKindRank: class TestRuleLabel: + def test_rule_label_lives_in_pfs_cite(self): + """Dossier task 13 moved ``rule_label`` to ``pfs.cite``; the chat's + import keeps working through the re-export.""" + import pfs.cite + + assert lineage.rule_label is pfs.cite.rule_label + def test_title_without_a_kind_word_is_rule_not_final(self): """Since CY2018 the CMS titles say neither "Proposed" nor "Final"; without a decided kind the label must not claim diff --git a/tests/llm/test_search.py b/tests/llm/test_search.py index 1f18bc6..d26b36c 100644 --- a/tests/llm/test_search.py +++ b/tests/llm/test_search.py @@ -425,3 +425,54 @@ class TestDedupeByLabel: "", ] assert out[0]["item_key"] == "B" + + +class TestItemKeys: + """Dossier task 13: ``item_keys`` restricts a search to a set of items.""" + + def test_item_key_set_is_pushed_into_the_store_filter(self): + assert search._with_item_keys({}, ["K1", "K2"]) == { + "item_key": {"$in": ["K1", "K2"]} + } + assert search._with_item_keys({"kind": "corpus"}, ("K1",)) == { + "kind": "corpus", + "item_key": {"$in": ["K1"]}, + } + theme_or = {"$or": [{"theme_1": "x"}]} + assert search._with_item_keys(theme_or, ["K1"]) == { + "$and": [theme_or, {"item_key": {"$in": ["K1"]}}] + } + both = {"$and": [{"doctype": "manual"}, theme_or]} + assert search._with_item_keys(both, ["K1"]) == { + "$and": [{"doctype": "manual"}, theme_or, {"item_key": {"$in": ["K1"]}}] + } + # an equality on item_key and the set are both kept + assert search._with_item_keys({"item_key": "K9"}, ["K1"]) == { + "$and": [{"item_key": "K9"}, {"item_key": {"$in": ["K1"]}}] + } + assert search._with_item_keys({"kind": "x"}, None) == {"kind": "x"} + + @patch("llm.search.PoolEmbeddings") + @patch("llm.index.vectorstore") + def test_search_passes_item_keys_to_the_store(self, mock_vs, MockEmb): + MockEmb.return_value.embed_query.return_value = [0.0, 0.0, 0.0] + store = MagicMock() + store.similarity_search_with_score_by_vector.return_value = [] + mock_vs.return_value = store + run_search( + "q", + cfg=CFG, + pool=MagicMock(), + collection="corpus", + item_keys=["K1", "K2"], + limit=3, + ) + kwargs = store.similarity_search_with_score_by_vector.call_args.kwargs + assert kwargs["filter"] == {"item_key": {"$in": ["K1", "K2"]}} + + @patch("llm.search.PoolEmbeddings") + @patch("llm.index.vectorstore") + def test_an_empty_key_set_finds_nothing(self, mock_vs, MockEmb): + assert run_search("q", cfg=CFG, pool=MagicMock(), item_keys=[]) == [] + mock_vs.assert_not_called() + MockEmb.assert_not_called() diff --git a/tests/pfs/conftest.py b/tests/pfs/conftest.py new file mode 100644 index 0000000..67929d6 --- /dev/null +++ b/tests/pfs/conftest.py @@ -0,0 +1,3 @@ +"""Shared pfs fixtures: the HOME-VISITS proof family (dossier task 13).""" + +from tests.pfs.home_visits_fixture import home_fixture # noqa: F401 diff --git a/tests/pfs/fixtures/home_visits_fr.jsonl b/tests/pfs/fixtures/home_visits_fr.jsonl new file mode 100644 index 0000000..88418ed --- /dev/null +++ b/tests/pfs/fixtures/home_visits_fr.jsonl @@ -0,0 +1,33 @@ +{"item_key": "PETM225D", "p_id": 390, "page": 69440, "ordinal": 4, "text": "When we establish values for codes or consider whether codes are potentially misvalued under the PFS, we take into account the resources involved in furnishing the specific service as described by the CPT code. As such, historically, we do not take into account: (1) travel costs incurred by the physician or other practitioner; (2) potential opportunity costs to a physician or other practitioner when care is delivered in one setting versus another; or (3) the physician or other practitioner's work and time expended in performing activities that are outside the scope of the specific service as described by the CPT code. These are not considered to be resources involved in furnishing the service, and they are not included in establishing payment rates under the PFS in accordance with section 1848 of the Act, and, as such, do not provide justification for potential misvaluation of those payments. That said, in February 2021, the AMA CPT Editorial Panel deleted the family of domiciliary codes, CPT codes 99324 to 99340, and merged the services described by those codes into the existing family of home-based E/M visits, CPT codes 99341 to 99350 (a range of codes that includes CPT codes 99344, 99345, 99349, and 99350). In addition, the AMA RUC made recommendations regarding the values for these home-based E/M codes as discussed in section II.F. of the CY 2023 PFS proposed rule (87 FR 45999) and in section II.F. of this final rule. Since CMS had already received AMA RUC recommendations for these home-based E/M visit codes, we considered those recommendations and solicited additional public comments, recommendations, and independent analysis as supporting evidence from all interested parties regarding the valuations for the home-based E/M visits, including CPT codes 99344, 99345, 99349, and 99350. Because we discussed and solicited public comment on the valuation of these codes in the proposed rule, we stated that we were not considering these home-based E/M ( printed page 69441) visits as potentially misvalued for CY 2023.", "title": "Medicare and Medicaid Programs; CY 2023 Payment Policies Under the Physician Fee Schedule and Other Changes to Part B Payment and Coverage Policies; Medicare Shared Savings Program Requirements; Implementing Requirements for Manufacturers of Certain Single-dose Container or Single-use Package Drugs To Provide Refunds With Respect to Discarded Amounts; and COVID-19 Interim Final Rules", "date_published": "2022-11-18", "document_number": "2022-23873", "html_url": "https://www.federalregister.gov/documents/2022/11/18/2022-23873/medicare-and-medicaid-programs-cy-2023-payment-policies-under-the-physician-fee-schedule-and-other", "start_page": 69404, "end_page": 70700, "fr_volume": 87} +{"item_key": "PETM225D", "p_id": 1672, "page": 69608, "ordinal": 6, "text": "More specifically, in its February 2021 meeting, effective beginning in 2023, the CPT Editorial Panel deleted the nine CPT codes in the Domiciliary, Rest Home (for example, Boarding Home), or Custodial Care Services code family (CPT codes 99324-99328, and 99334-99337), and one CPT code in the Home Services family (CPT code 99343), to merge these services with the eight remaining home visit services. The eight remaining home services CPT codes (99341, 99342, 99344, 99345, and 99347-99350) were revised to describe Home or Residence Services to align with the principles of the O/O E/M visit codes by allowing physicians and NPPs to document and select the level of service based on total practitioner time or MDM level. These changes include combining the domiciliary, rest home and custodial care CPT codes with the home visit CPT codes, resulting in a single family of CPT codes that describe these types of services. In addition, CPT revised the descriptors to allow reporting that is based on time or MDM level—in alignment with the O/O E/M visit CPT codes. We proposed to accept these coding revisions.", "title": "Medicare and Medicaid Programs; CY 2023 Payment Policies Under the Physician Fee Schedule and Other Changes to Part B Payment and Coverage Policies; Medicare Shared Savings Program Requirements; Implementing Requirements for Manufacturers of Certain Single-dose Container or Single-use Package Drugs To Provide Refunds With Respect to Discarded Amounts; and COVID-19 Interim Final Rules", "date_published": "2022-11-18", "document_number": "2022-23873", "html_url": "https://www.federalregister.gov/documents/2022/11/18/2022-23873/medicare-and-medicaid-programs-cy-2023-payment-policies-under-the-physician-fee-schedule-and-other", "start_page": 69404, "end_page": 70700, "fr_volume": 87} +{"item_key": "PETM225D", "p_id": 1674, "page": 69608, "ordinal": 8, "text": "Comment: The commenters supported our proposal to accept the CPT coding changes for Home or Residence Services codes.", "title": "Medicare and Medicaid Programs; CY 2023 Payment Policies Under the Physician Fee Schedule and Other Changes to Part B Payment and Coverage Policies; Medicare Shared Savings Program Requirements; Implementing Requirements for Manufacturers of Certain Single-dose Container or Single-use Package Drugs To Provide Refunds With Respect to Discarded Amounts; and COVID-19 Interim Final Rules", "date_published": "2022-11-18", "document_number": "2022-23873", "html_url": "https://www.federalregister.gov/documents/2022/11/18/2022-23873/medicare-and-medicaid-programs-cy-2023-payment-policies-under-the-physician-fee-schedule-and-other", "start_page": 69404, "end_page": 70700, "fr_volume": 87} +{"item_key": "PETM225D", "p_id": 1675, "page": 69608, "ordinal": 9, "text": "Response: We appreciate the feedback from the commenters regarding our proposal, and are finalizing as proposed to adopt the CPT merger of the home and domiciliary visits into one family, and adopt the CPT codes as revised for reporting these services.", "title": "Medicare and Medicaid Programs; CY 2023 Payment Policies Under the Physician Fee Schedule and Other Changes to Part B Payment and Coverage Policies; Medicare Shared Savings Program Requirements; Implementing Requirements for Manufacturers of Certain Single-dose Container or Single-use Package Drugs To Provide Refunds With Respect to Discarded Amounts; and COVID-19 Interim Final Rules", "date_published": "2022-11-18", "document_number": "2022-23873", "html_url": "https://www.federalregister.gov/documents/2022/11/18/2022-23873/medicare-and-medicaid-programs-cy-2023-payment-policies-under-the-physician-fee-schedule-and-other", "start_page": 69404, "end_page": 70700, "fr_volume": 87} +{"item_key": "PETM225D", "p_id": 1676, "page": 69608, "ordinal": 10, "text": "The RUC survey time includes pre-service time 3 days before the date of encounter, intraservice time on the date of encounter, and post-service time that includes 7 days after the date of encounter. These eight CPT codes were reviewed at the October 2021 RUC meeting with recommendations submitted to CMS for the CY 2023 rule cycle. The RUC recommended the survey 25th percentile value for all CPT codes in the Home or Residence Services code family, except for CPT code 99350, for which the RUC recommended the median value. We proposed the RUC-recommended work RVU for all eight CPT codes in the Home or Residence Services CPT code family. We proposed a work RVU of 1.00 for CPT code 99341 [CPT descriptor omitted], a work RVU of 1.65 for CPT code 99342 [CPT descriptor omitted], a work RVU of 2.87 for CPT code 99344 [CPT descriptor omitted], a work RVU of 3.88 for CPT code 99345 [CPT descriptor omitted], a work RVU of 0.90 for CPT code 99347 [CPT descriptor omitted], a work RVU of 1.50 for CPT code 99348 [CPT descriptor omitted], a work RVU of 2.44 for CPT code 99349 [CPT descriptor omitted], and a work RVU of 3.60 for CPT code 99350 [CPT descriptor omitted].", "title": "Medicare and Medicaid Programs; CY 2023 Payment Policies Under the Physician Fee Schedule and Other Changes to Part B Payment and Coverage Policies; Medicare Shared Savings Program Requirements; Implementing Requirements for Manufacturers of Certain Single-dose Container or Single-use Package Drugs To Provide Refunds With Respect to Discarded Amounts; and COVID-19 Interim Final Rules", "date_published": "2022-11-18", "document_number": "2022-23873", "html_url": "https://www.federalregister.gov/documents/2022/11/18/2022-23873/medicare-and-medicaid-programs-cy-2023-payment-policies-under-the-physician-fee-schedule-and-other", "start_page": 69404, "end_page": 70700, "fr_volume": 87} +{"item_key": "PETM225D", "p_id": 1677, "page": 69608, "ordinal": 11, "text": "We proposed the RUC-recommended direct PE inputs for CPT codes 99345 and 99347-99350 without refinement. For CPT codes 99341 and 99342, we are refining the direct PE inputs by removing supply item SK062 (patient education booklet). For CPT code 99344, we are refining the direct PE inputs by removing supply items SK062 (patient education booklet), SJ053 (swab-pad, alcohol), and SJ061 (tongue depressor). Per the PE Summary of Recommendations provided by the RUC, CPT codes 99341, 99342, 99344, and 99347 would typically have procedures performed on the same date of service. For those CPT codes, the RUC stated that they removed supplies that would be duplicative, such as gloves, alcohol wipes, booklet, and tongue depressor. However, we found that not all of these duplicative supplies had been removed from CPT codes ( printed page 69609) 99341, 99342, and 99344 by the RUC. Therefore, we proposed to remove these duplicative supplies from CPT codes 99341, 99342, and 99344, and accept the remaining RUC-recommended direct PE inputs without refinement.", "title": "Medicare and Medicaid Programs; CY 2023 Payment Policies Under the Physician Fee Schedule and Other Changes to Part B Payment and Coverage Policies; Medicare Shared Savings Program Requirements; Implementing Requirements for Manufacturers of Certain Single-dose Container or Single-use Package Drugs To Provide Refunds With Respect to Discarded Amounts; and COVID-19 Interim Final Rules", "date_published": "2022-11-18", "document_number": "2022-23873", "html_url": "https://www.federalregister.gov/documents/2022/11/18/2022-23873/medicare-and-medicaid-programs-cy-2023-payment-policies-under-the-physician-fee-schedule-and-other", "start_page": 69404, "end_page": 70700, "fr_volume": 87} +{"item_key": "PETM225D", "p_id": 1678, "page": 69609, "ordinal": 1, "text": "The following is a summary of the comments we received and our responses.", "title": "Medicare and Medicaid Programs; CY 2023 Payment Policies Under the Physician Fee Schedule and Other Changes to Part B Payment and Coverage Policies; Medicare Shared Savings Program Requirements; Implementing Requirements for Manufacturers of Certain Single-dose Container or Single-use Package Drugs To Provide Refunds With Respect to Discarded Amounts; and COVID-19 Interim Final Rules", "date_published": "2022-11-18", "document_number": "2022-23873", "html_url": "https://www.federalregister.gov/documents/2022/11/18/2022-23873/medicare-and-medicaid-programs-cy-2023-payment-policies-under-the-physician-fee-schedule-and-other", "start_page": 69404, "end_page": 70700, "fr_volume": 87} +{"item_key": "PETM225D", "p_id": 1679, "page": 69609, "ordinal": 2, "text": "Comment: The majority of commenters supported our proposal to accept the RUC-recommended RVUs for all of the Home or Residence Services codes.", "title": "Medicare and Medicaid Programs; CY 2023 Payment Policies Under the Physician Fee Schedule and Other Changes to Part B Payment and Coverage Policies; Medicare Shared Savings Program Requirements; Implementing Requirements for Manufacturers of Certain Single-dose Container or Single-use Package Drugs To Provide Refunds With Respect to Discarded Amounts; and COVID-19 Interim Final Rules", "date_published": "2022-11-18", "document_number": "2022-23873", "html_url": "https://www.federalregister.gov/documents/2022/11/18/2022-23873/medicare-and-medicaid-programs-cy-2023-payment-policies-under-the-physician-fee-schedule-and-other", "start_page": 69404, "end_page": 70700, "fr_volume": 87} +{"item_key": "PETM225D", "p_id": 1680, "page": 69609, "ordinal": 3, "text": "Response: We appreciate the feedback from the commenters regarding our proposal.", "title": "Medicare and Medicaid Programs; CY 2023 Payment Policies Under the Physician Fee Schedule and Other Changes to Part B Payment and Coverage Policies; Medicare Shared Savings Program Requirements; Implementing Requirements for Manufacturers of Certain Single-dose Container or Single-use Package Drugs To Provide Refunds With Respect to Discarded Amounts; and COVID-19 Interim Final Rules", "date_published": "2022-11-18", "document_number": "2022-23873", "html_url": "https://www.federalregister.gov/documents/2022/11/18/2022-23873/medicare-and-medicaid-programs-cy-2023-payment-policies-under-the-physician-fee-schedule-and-other", "start_page": 69404, "end_page": 70700, "fr_volume": 87} +{"item_key": "PETM225D", "p_id": 1681, "page": 69609, "ordinal": 4, "text": "Comment: A few commenters stated the RVUs for the Home or Residence Services code family were too low, and fail to adequately account for travel, addressing social determinants of health, and other comprehensive care. One commenter suggested that we maintain the current RVUs for codes 99341, 99344, 99345, 99347, and 99348, for which the RUC-recommended RVUs decreased, while supporting our proposal to accept the increased RVUs for codes 99342, 99349, and 99350 recommended by the RUC. Another commenter suggested that we increase the RVUs for the entire code family to reflect travel expenses, and expressed concern that unreimbursed travel will be detrimental to the care provided to very ill patients and threaten the financial viability of physician practices that provide home or residence visits.", "title": "Medicare and Medicaid Programs; CY 2023 Payment Policies Under the Physician Fee Schedule and Other Changes to Part B Payment and Coverage Policies; Medicare Shared Savings Program Requirements; Implementing Requirements for Manufacturers of Certain Single-dose Container or Single-use Package Drugs To Provide Refunds With Respect to Discarded Amounts; and COVID-19 Interim Final Rules", "date_published": "2022-11-18", "document_number": "2022-23873", "html_url": "https://www.federalregister.gov/documents/2022/11/18/2022-23873/medicare-and-medicaid-programs-cy-2023-payment-policies-under-the-physician-fee-schedule-and-other", "start_page": 69404, "end_page": 70700, "fr_volume": 87} +{"item_key": "PETM225D", "p_id": 1682, "page": 69609, "ordinal": 5, "text": "Response: We continue to believe that the RUC-recommended RVUs are the appropriate values for CPT codes 99341, 99342, 99344, 99345, and 99347-99350. We appreciate the commenters' remarks, and we acknowledge the concerns regarding providing patient care and addressing social determinants of health and other issues during home or residence visits. Historically, travel costs incurred by the physician or practitioner are not included in the valuation of E/M codes, since travel time and/or mileage is not considered a resource involved in furnishing the service. The RUC survey for the Home or Residence Services code family did not include information on physician travel or mileage. Also, the CPT E/M guidelines for selecting the level of home or residence service, when performed based on time, specifically says not to count the time spent on travel (2023 CPT Codebook, p. 26). Therefore, we are finalizing the RUC-recommended work RVUs as proposed.", "title": "Medicare and Medicaid Programs; CY 2023 Payment Policies Under the Physician Fee Schedule and Other Changes to Part B Payment and Coverage Policies; Medicare Shared Savings Program Requirements; Implementing Requirements for Manufacturers of Certain Single-dose Container or Single-use Package Drugs To Provide Refunds With Respect to Discarded Amounts; and COVID-19 Interim Final Rules", "date_published": "2022-11-18", "document_number": "2022-23873", "html_url": "https://www.federalregister.gov/documents/2022/11/18/2022-23873/medicare-and-medicaid-programs-cy-2023-payment-policies-under-the-physician-fee-schedule-and-other", "start_page": 69404, "end_page": 70700, "fr_volume": 87} +{"item_key": "PETM225D", "p_id": 1683, "page": 69609, "ordinal": 6, "text": "Comment: One commenter requested that we not refine the direct PE inputs for codes 99341, 99342, and 99344 as proposed. For CPT codes 99341 and 99342, we proposed removing supply item SK062 (patient education booklet). For CPT code 99344, we proposed removing supply items SK062 (patient education booklet), SJ053 (swab-pad, alcohol), and SJ061 (tongue depressor).", "title": "Medicare and Medicaid Programs; CY 2023 Payment Policies Under the Physician Fee Schedule and Other Changes to Part B Payment and Coverage Policies; Medicare Shared Savings Program Requirements; Implementing Requirements for Manufacturers of Certain Single-dose Container or Single-use Package Drugs To Provide Refunds With Respect to Discarded Amounts; and COVID-19 Interim Final Rules", "date_published": "2022-11-18", "document_number": "2022-23873", "html_url": "https://www.federalregister.gov/documents/2022/11/18/2022-23873/medicare-and-medicaid-programs-cy-2023-payment-policies-under-the-physician-fee-schedule-and-other", "start_page": 69404, "end_page": 70700, "fr_volume": 87} +{"item_key": "PETM225D", "p_id": 1684, "page": 69609, "ordinal": 7, "text": "Response: Per the PE Summary of Recommendations provided by the RUC, CPT codes 99341, 99342, 99344, and 99347 would typically have procedures performed on the same date of service, which would already include some of the same supply items. For these CPT codes, the RUC stated that they had removed the PE inputs for supplies that would be duplicative with the procedure on the same day, such as gloves, alcohol wipes, a booklet, and a tongue depressor. Although the RUC did remove the duplicative supplies for CPT code 99347 from the direct PE inputs they recommended, we found that the RUC had not removed all of these duplicative supplies from CPT codes 99341, 99342, and 99344. Therefore, we proposed to remove these duplicative supplies from the direct PE inputs for CPT codes 99341, 99342, and 99344. We continue to believe these supplies are duplicative with a same-day procedure, and are, therefore, finalizing the direct PE inputs for CPT codes 99341, 99342, 99344, and 99347 as proposed.", "title": "Medicare and Medicaid Programs; CY 2023 Payment Policies Under the Physician Fee Schedule and Other Changes to Part B Payment and Coverage Policies; Medicare Shared Savings Program Requirements; Implementing Requirements for Manufacturers of Certain Single-dose Container or Single-use Package Drugs To Provide Refunds With Respect to Discarded Amounts; and COVID-19 Interim Final Rules", "date_published": "2022-11-18", "document_number": "2022-23873", "html_url": "https://www.federalregister.gov/documents/2022/11/18/2022-23873/medicare-and-medicaid-programs-cy-2023-payment-policies-under-the-physician-fee-schedule-and-other", "start_page": 69404, "end_page": 70700, "fr_volume": 87} +{"item_key": "PETM225D", "p_id": 1685, "page": 69609, "ordinal": 8, "text": "After consideration of the public comments, we are finalizing the work RVU values for the Home or Residence Services code family as proposed. We are also finalizing the direct PE inputs for these codes as proposed.", "title": "Medicare and Medicaid Programs; CY 2023 Payment Policies Under the Physician Fee Schedule and Other Changes to Part B Payment and Coverage Policies; Medicare Shared Savings Program Requirements; Implementing Requirements for Manufacturers of Certain Single-dose Container or Single-use Package Drugs To Provide Refunds With Respect to Discarded Amounts; and COVID-19 Interim Final Rules", "date_published": "2022-11-18", "document_number": "2022-23873", "html_url": "https://www.federalregister.gov/documents/2022/11/18/2022-23873/medicare-and-medicaid-programs-cy-2023-payment-policies-under-the-physician-fee-schedule-and-other", "start_page": 69404, "end_page": 70700, "fr_volume": 87} +{"item_key": "PETM225D", "p_id": 1686, "page": 69609, "ordinal": 9, "text": "We proposed that prolonged home or residence services by a physician or NPP would be reportable using HCPCS code G0318 ( Prolonged home or residence evaluation and management service(s) beyond the total time for the primary service (when the primary service has been selected using time on the date of the primary service); each additional 15 minutes by the physician or qualified healthcare professional, with or without direct patient contact (list separately in addition to CPT codes 99345, 99350 for home or residence evaluation and management services). (Do not report G0318 on the same date of service as other prolonged services for evaluation and management 99358, 99359, 99417). (Do not report G0318 for any time unit less than 15 minutes)). Code G0318 would be reportable when the total time for the home or residence visit (specified in the time file) is exceeded by 15 or more minutes. Prolonged services (whether on the same date or another date within the surveyed timeframe) would be reportable as an add-on code to CPT codes 99345 or 99350 once the practitioner spends 15+ minutes beyond the total time finalized for the primary service (as specified in the time file). We would allow the physician or NPP to include any prolonged service time spent within the surveyed timeframe for the Home or Residence Services code family, which includes pre-service time 3 days before the date of encounter, intraservice time on the date of encounter, and post-service time that includes 7 days after the date of encounter. This means that for CPT code 99345, assuming we finalized the RUC-recommended total time of 126 minutes, prolonged services would be reportable once 141 or more minutes are spent by a physician or NPP providing the home or residence visit. Likewise, for CPT code 99350, assuming we finalized the RUC-recommended total time of 97 minutes, prolonged services would be reportable once 112 or more minutes are spent by a physician or NPP providing the home or residence visit. See Table 18 in our proposed rule for a table summarizing this information.", "title": "Medicare and Medicaid Programs; CY 2023 Payment Policies Under the Physician Fee Schedule and Other Changes to Part B Payment and Coverage Policies; Medicare Shared Savings Program Requirements; Implementing Requirements for Manufacturers of Certain Single-dose Container or Single-use Package Drugs To Provide Refunds With Respect to Discarded Amounts; and COVID-19 Interim Final Rules", "date_published": "2022-11-18", "document_number": "2022-23873", "html_url": "https://www.federalregister.gov/documents/2022/11/18/2022-23873/medicare-and-medicaid-programs-cy-2023-payment-policies-under-the-physician-fee-schedule-and-other", "start_page": 69404, "end_page": 70700, "fr_volume": 87} +{"item_key": "PETM225D", "p_id": 1694, "page": 69610, "ordinal": 6, "text": "After consideration of the public comments, we are finalizing our proposal to create new code G0318 for a prolonged home or residence visit. We are also finalizing our proposal to change the status indicator for prolonged CPT codes 99358 and 99359 to “I,” which indicates that these codes are not valid for Medicare purposes, and that Medicare uses another code for reporting of, and payment for, these services.", "title": "Medicare and Medicaid Programs; CY 2023 Payment Policies Under the Physician Fee Schedule and Other Changes to Part B Payment and Coverage Policies; Medicare Shared Savings Program Requirements; Implementing Requirements for Manufacturers of Certain Single-dose Container or Single-use Package Drugs To Provide Refunds With Respect to Discarded Amounts; and COVID-19 Interim Final Rules", "date_published": "2022-11-18", "document_number": "2022-23873", "html_url": "https://www.federalregister.gov/documents/2022/11/18/2022-23873/medicare-and-medicaid-programs-cy-2023-payment-policies-under-the-physician-fee-schedule-and-other", "start_page": 69404, "end_page": 70700, "fr_volume": 87} +{"item_key": "PETM225D", "p_id": 3607, "page": 69823, "ordinal": 3, "text": "As proposed, CPT codes 99341 through 99350 would be described as codes for evaluation and management services furnished in a patient's home, without the place of service 12 identifier. The place of service logic is included in claims processing algorithms, and therefore, accounted for in paid claims used by the Shared Savings Program in determining beneficiary assignment. As described in Medicare Claims Processing Manual, Publication 100-04, Chapter 26, place of service codes are two-digit codes placed on health care professional claims to indicate the setting in which a service was provided. Claims submitted for services that are allowable when provided in certain settings will process only when the appropriate place of service is included on the claim. Place of service 12 is defined as “location, other than a hospital or other facility, where the patient receives care in a private residence.” In previous rulemaking, we updated the reference to CPT codes 99341 through 99350 in the definition of primary care services at § 425.400(c) to include place of service 12 for clarity; however, as discussed in the proposed rule, we now believe it is no longer accurate as these codes have been revised to include multiple places of service, any of which we would consider to be the patient's home.", "title": "Medicare and Medicaid Programs; CY 2023 Payment Policies Under the Physician Fee Schedule and Other Changes to Part B Payment and Coverage Policies; Medicare Shared Savings Program Requirements; Implementing Requirements for Manufacturers of Certain Single-dose Container or Single-use Package Drugs To Provide Refunds With Respect to Discarded Amounts; and COVID-19 Interim Final Rules", "date_published": "2022-11-18", "document_number": "2022-23873", "html_url": "https://www.federalregister.gov/documents/2022/11/18/2022-23873/medicare-and-medicaid-programs-cy-2023-payment-policies-under-the-physician-fee-schedule-and-other", "start_page": 69404, "end_page": 70700, "fr_volume": 87} +{"item_key": "54GTKR5G", "p_id": 2240, "page": 66361, "ordinal": 13, "text": "For CPT code 99326 [CPT descriptor omitted]; CPT code 99327 [CPT descriptor omitted]; CPT code 99328 [CPT descriptor omitted]; CPT code 99334 [CPT descriptor omitted]; CPT code 99335 [CPT descriptor omitted]; CPT code 99336 [CPT descriptor omitted]; CPT code 99337 [CPT descriptor omitted]; CPT code 99343 [CPT descriptor omitted]; CPT code 99344 [CPT descriptor omitted]; CPT code 99345 [CPT descriptor omitted]; CPT code 99347 [CPT descriptor omitted]; CPT code 99348 [CPT descriptor omitted]; CPT code 99349 [CPT descriptor omitted]; and CPT code 99350 [CPT descriptor omitted], the RUC recommended that the work RVUs for these codes be maintained at their current values: 2.27 work RVUs for CPT code 99326; 3.03 work RVUs for CPT code 99327; 3.78 work RVUs for CPT code 99328; 0.76 work RVUs for CPT code 99334; 1.26 work RVUs for CPT code 99335; 2.02 work RVUs for CPT code 99336; 3.03 work RVUs for CPT code 99337; 2.27 work RVUs for CPT code 99343; 3.03 for CPT code 99344; 3.78 work RVUs for CPT code 99345; 0.76 work RVUs for CPT code 99347; 1.26 work RVUs for CPT code 99348; 2.02 work RVUs for CPT code 99349; and 3.03 work RVUs for CPT code 99350, which we accepted.", "title": "Medicare Program; CY 2008 PFS Final Rule", "date_published": "2007-11-27", "document_number": "07-5506", "html_url": "https://www.federalregister.gov/documents/2007/11/27/07-5506/medicare-program-revisions-to-payment-policies-under-the-physician-fee-schedule-and-other-part-b", "start_page": 66222, "end_page": 66578, "fr_volume": 72} +{"item_key": "54GTKR5G", "p_id": 2241, "page": 66362, "ordinal": 1, "text": "Comment: Commenters disagreed with the RUC-recommended work values for these services, which we had accepted. The commenters disagreed with the RUC-recommended work RVUs and believed the services were undervalued. The commenters also believed that the home visit work RVUs should remain “relatively” the same with respect to office visit codes as they did prior to the five-year review and requested that CMS reject the RUC recommended work RVUs and follow their survey values. Based on these comments, we referred these codes to the multi-specialty validation panel for review.", "title": "Medicare Program; CY 2008 PFS Final Rule", "date_published": "2007-11-27", "document_number": "07-5506", "html_url": "https://www.federalregister.gov/documents/2007/11/27/07-5506/medicare-program-revisions-to-payment-policies-under-the-physician-fee-schedule-and-other-part-b", "start_page": 66222, "end_page": 66578, "fr_volume": 72} +{"item_key": "54GTKR5G", "p_id": 2242, "page": 66362, "ordinal": 2, "text": "Response: As a result of the statistical analysis of the 2007 multi-specialty validation panel ratings, we have assigned 2.63 work RVUs to CPT code 99326; 3.46 work RVUs to CPT code 99327; 4.09 work RVUs to CPT code 99328; 1.07 work RVUs to CPT code 99334; 1.72 work RVUs to CPT code 99335; 2.46 work RVUs to CPT code 99336; 3.58 work RVUs to CPT code 99337; 2.53 work RVUs to CPT code 99343; 3.38 work RVUs to CPT code 99344; 4.09 work RVUs to CPT code 99345; 1.00 work RVUs to CPT code 99347; 1.56 work RVUs to CPT code 99348; 2.33 work RVUs to CPT code 99349; and 3.28 work RVUs to CPT code 99350.", "title": "Medicare Program; CY 2008 PFS Final Rule", "date_published": "2007-11-27", "document_number": "07-5506", "html_url": "https://www.federalregister.gov/documents/2007/11/27/07-5506/medicare-program-revisions-to-payment-policies-under-the-physician-fee-schedule-and-other-part-b", "start_page": 66222, "end_page": 66578, "fr_volume": 72} +{"item_key": "NHRGIHGD", "p_id": 1469, "page": 49463, "ordinal": 9, "text": "After reviewing all the comments, we are finalizing as proposed, to allow HCPCS code G2211 to be billed as an add-on code with the home or residence E/M visits code family (CPT codes 99341, 99342, 99344, 99345, 99347, 99348, 99349, 99350). We are also finalizing refinement of the HCPCS code G2211 code descriptor to read as follows, “ (Visit complexity inherent to evaluation and management associated with medical care services that serve as the continuing focal point for all needed health care services and/or with medical care services that are part of ongoing care related to a patient's single, serious ( printed page 49464) condition or a complex condition. (Add-on code, list separately in addition to home or residence or office/outpatient evaluation and management service, new or established)) ”.", "title": "Medicare and Medicaid Programs; CY 2026 Payment Policies Under the Physician Fee Schedule and Other Changes to Part B Payment and Coverage Policies; Medicare Shared Savings Program Requirements; and Medicare Prescription Drug Inflation Rebate Program", "date_published": "2025-11-05", "document_number": "2025-19787", "html_url": "https://www.federalregister.gov/documents/2025/11/05/2025-19787/medicare-and-medicaid-programs-cy-2026-payment-policies-under-the-physician-fee-schedule-and-other", "start_page": 49266, "end_page": 50481, "fr_volume": 90} +{"item_key": "JCWARTJD", "p_id": 1168, "page": 71098, "ordinal": 11, "text": "After consideration of public comments, we are finalizing the creation of modifier B1 as proposed. We note that modifier MOD1 was a placeholder code in the proposed rule. The finalized modifier descriptor for modifier B1 is: ( Visit complexity inherent to new or established office/outpatient or home or residence evaluation and management service, associated with medical care services that serve as the continuing focal point for all needed health care services and/or with medical care services that are part of ongoing care related to a patient's single, serious condition or a complex condition).", "title": "Medicare and Medicaid Programs; CY 2027 Payment Policies Under the Physician Fee Schedule and Other Changes to Part B Payment and Coverage Policies; Medicare Shared Savings Program Requirements; and Medicare Prescription Drug Inflation Rebate Program", "date_published": "2026-11-09", "document_number": "2026-22743", "html_url": "https://www.federalregister.gov/documents/2026/11/09/2026-22743/medicare-and-medicaid-programs-cy-2027-payment-policies-under-the-physician-fee-schedule-and-other", "start_page": 70992, "end_page": 72020, "fr_volume": 91} +{"item_key": "JCWARTJD", "p_id": 1205, "page": 71102, "ordinal": 5, "text": "After consideration of public comments, we are finalizing modifier B2 as proposed. We note that modifier MOD2 was a placeholder code in the proposed rule. The finalized modifier descriptor is B2 ( Visit complexity inherent to new or established office/outpatient or home or residence evaluation and management service, associated with medical care services furnished by a participant or practitioner participating in a Medicare accountable care organization. Services must serve as the continuing focal point for all needed health care services and/or be part of ongoing care related to a patient's single, serious condition or complex condition.).", "title": "Medicare and Medicaid Programs; CY 2027 Payment Policies Under the Physician Fee Schedule and Other Changes to Part B Payment and Coverage Policies; Medicare Shared Savings Program Requirements; and Medicare Prescription Drug Inflation Rebate Program", "date_published": "2026-11-09", "document_number": "2026-22743", "html_url": "https://www.federalregister.gov/documents/2026/11/09/2026-22743/medicare-and-medicaid-programs-cy-2027-payment-policies-under-the-physician-fee-schedule-and-other", "start_page": 70992, "end_page": 72020, "fr_volume": 91} +{"item_key": "MZ24MX5S", "p_id": 877, "page": 45999, "ordinal": 6, "text": "In February 2021, the CPT Editorial Panel deleted the nine CPT codes in the Domiciliary, Rest Home (for example, Boarding Home), or Custodial Care Services code family (CPT codes 99324-99328, and 99334-99337), and one CPT code in the Home Services family (CPT code 99343), to merge these services with the eight remaining home visit services. The eight remaining home services CPT codes (99341, 99342, 99344, 99345, and 99347-99350) were revised to describe Home or Residence Services to align with the principles of the O/O E/M visit codes by allowing physicians and NPPs to document and select the level of service based on total practitioner time or MDM level. For CY 2023, the home and domiciliary E/M code family will be revised by the CPT to include services provided in assisted living facilities, group homes, custodial care facilities, and residential substance abuse treatment facilities, as well as a patient's home. These changes include combining the domiciliary and rest home CPT codes with the home visit CPT codes, resulting in a single family of CPT codes that describe these types of services. In addition, CPT revised the descriptors to allow reporting that is based on time or MDM level—in alignment with the O/O E/M visit CPT codes. The RUC survey time includes pre-service time 3 days before the date of encounter, intraservice time on the date of encounter, and post-service time that includes 7 days after the date of encounter. These eight CPT codes were reviewed at the October 2021 RUC meeting with recommendations submitted to CMS for the CY 2023 rule cycle. The RUC recommended the survey 25th percentile value for all CPT codes in the Home or Residence Services code family, except for CPT code 99350, for which the RUC recommended the median value. ( printed page 46000)", "title": "Medicare and Medicaid Programs; CY 2023 Payment Policies Under the Physician Fee Schedule and Other Changes to Part B Payment Policies; Medicare Shared Savings Program Requirements; Medicare and Medicaid Provider Enrollment Policies, Including for Skilled Nursing Facilities; Conditions of Payment for Suppliers of Durable Medicaid Equipment, Prosthetics, Orthotics, and Supplies (DMEPOS); and Implementing Requirements for Manufacturers of Certain Single-Dose Container or Single-Use Package Drugs To Provide Refunds With Respect to Discarded Amounts", "date_published": "2022-07-29", "document_number": "2022-14562", "html_url": "https://www.federalregister.gov/documents/2022/07/29/2022-14562/medicare-and-medicaid-programs-cy-2023-payment-policies-under-the-physician-fee-schedule-and-other", "start_page": 45860, "end_page": 46843, "fr_volume": 87} +{"item_key": "MZ24MX5S", "p_id": 878, "page": 46000, "ordinal": 1, "text": "We are proposing the RUC-recommended work RVU for all eight CPT codes in the Home or Residence Services CPT code family. We are proposing a work RVU of 1.00 for CPT code 99341 [CPT descriptor omitted], a work RVU of 1.65 for CPT code 99342 [CPT descriptor omitted], a work RVU of 2.87 for CPT code 99344 [CPT descriptor omitted], a work RVU of 3.88 for CPT code 99345 [CPT descriptor omitted], a work RVU of 0.90 for CPT code 99347 [CPT descriptor omitted], a work RVU of 1.50 for CPT code 99348 [CPT descriptor omitted], a work RVU of 2.44 for CPT code 99349 [CPT descriptor omitted], and a work RVU of 3.60 for CPT code 99350 [CPT descriptor omitted].", "title": "Medicare and Medicaid Programs; CY 2023 Payment Policies Under the Physician Fee Schedule and Other Changes to Part B Payment Policies; Medicare Shared Savings Program Requirements; Medicare and Medicaid Provider Enrollment Policies, Including for Skilled Nursing Facilities; Conditions of Payment for Suppliers of Durable Medicaid Equipment, Prosthetics, Orthotics, and Supplies (DMEPOS); and Implementing Requirements for Manufacturers of Certain Single-Dose Container or Single-Use Package Drugs To Provide Refunds With Respect to Discarded Amounts", "date_published": "2022-07-29", "document_number": "2022-14562", "html_url": "https://www.federalregister.gov/documents/2022/07/29/2022-14562/medicare-and-medicaid-programs-cy-2023-payment-policies-under-the-physician-fee-schedule-and-other", "start_page": 45860, "end_page": 46843, "fr_volume": 87} +{"item_key": "MZ24MX5S", "p_id": 880, "page": 46000, "ordinal": 3, "text": "We are proposing that prolonged home or residence services by a physician or NPP would be reportable under GXXX3 ( Prolonged home or residence evaluation and management service(s) beyond the total time for the primary service (when the primary service has been selected using time on the date of the primary service); each additional 15 minutes by the physician or qualified healthcare professional, with or without direct patient contact (list separately in addition to CPT codes 99345, 99350 for home or residence evaluation and management services). (Do not report GXXX3 on the same date of service as other prolonged services for evaluation and management 99358, 99359, 99417). (Do not report GXXX3 for any time unit less than 15 minutes)). Code GXXX3 would be reportable when the total time (in the time file) is exceeded by 15 or more minutes. Prolonged services (whether on the same date or another date within the surveyed timeframe) would be reportable as an add-on code to CPT codes 99345 or 99350 once the practitioner spends 15+ minutes beyond the total time finalized for the primary service (in time file). We would allow the physician or NPP to include any prolonged service time spent within the surveyed timeframe for the home or residence services code family, which includes pre-service time 3 days before the date of encounter, intraservice time on the date of encounter, and post-service time that includes 7 days after the date of encounter. This means that for CPT code 99345, assuming we finalize the RUC-recommended total time of 126 minutes, prolonged services would be reportable once 141 or more minutes are spent by a physician or NPP providing home or residence services. Likewise, for CPT code 99350, assuming we finalize the RUC-recommended total time of 97 minutes, prolonged services would be reportable once 112 or more minutes are spent by a physician or NPP providing home or residence services. See Table 18 in section II.F.11.e. of this proposed rule for a table summarizing this information.", "title": "Medicare and Medicaid Programs; CY 2023 Payment Policies Under the Physician Fee Schedule and Other Changes to Part B Payment Policies; Medicare Shared Savings Program Requirements; Medicare and Medicaid Provider Enrollment Policies, Including for Skilled Nursing Facilities; Conditions of Payment for Suppliers of Durable Medicaid Equipment, Prosthetics, Orthotics, and Supplies (DMEPOS); and Implementing Requirements for Manufacturers of Certain Single-Dose Container or Single-Use Package Drugs To Provide Refunds With Respect to Discarded Amounts", "date_published": "2022-07-29", "document_number": "2022-14562", "html_url": "https://www.federalregister.gov/documents/2022/07/29/2022-14562/medicare-and-medicaid-programs-cy-2023-payment-policies-under-the-physician-fee-schedule-and-other", "start_page": 45860, "end_page": 46843, "fr_volume": 87} +{"item_key": "5ITGVDJV", "p_id": 521, "page": 43898, "ordinal": 9, "text": "Since we began actively paying for HCPCS code G2211 in CY 2024, we have come to believe that the resource costs of furnishing longitudinal care for beneficiaries is not best characterized as a separate service requiring a separate code. Rather, we believe that since this work is an inherent part of the visit, it would be more accurately valued as a modifier to the base E/M code. We also believe that transitioning HCPCS code G2211 from an add-on code to a modifier will be more streamlined from an operational perspective. This should also reduce operational burden, as it will not require the submission of a separate claim line, because the modifier will be placed on the claim ( printed page 43899) line for the associated E/M code. We are therefore proposing to replace HCPCS code G2211 with a modifier, which we will refer to in this proposed rule as MOD1, which is a placeholder that would be replaced with a two-digit HCPCS modifier, if finalized.", "title": "Medicare and Medicaid Programs; CY 2027 Payment Policies Under the Physician Fee Schedule and Other Changes to Part B Payment and Coverage Policies; Medicare Shared Savings Program Requirements; and Medicare Prescription Drug Inflation Rebate Program", "date_published": "2026-07-16", "document_number": "2026-14327", "html_url": "https://www.federalregister.gov/documents/2026/07/16/2026-14327/medicare-and-medicaid-programs-cy-2027-payment-policies-under-the-physician-fee-schedule-and-other", "start_page": 43842, "end_page": 44557, "fr_volume": 91} +{"item_key": "5ITGVDJV", "p_id": 537, "page": 43900, "ordinal": 7, "text": "We believe that MOD2 aligns with the goals of the Shared Savings Program and LEAD, which involve groups of health care providers working together to enhance beneficiary health through high quality, longitudinal primary and preventative care. One of the features of Shared Savings Program and LEAD ACOs is that beneficiaries benefit from ACO participants balancing goals of having total cost of care accountability and improving quality of care, while avoiding unnecessary services and ( printed page 43901) medical errors. While the specifics vary between the Shared Savings Program and the LEAD model, in general, participating ACOs are required to report quality measures that align with these objectives, and they are measured against their past performance, and the performance of similar ACOs.[20]", "title": "Medicare and Medicaid Programs; CY 2027 Payment Policies Under the Physician Fee Schedule and Other Changes to Part B Payment and Coverage Policies; Medicare Shared Savings Program Requirements; and Medicare Prescription Drug Inflation Rebate Program", "date_published": "2026-07-16", "document_number": "2026-14327", "html_url": "https://www.federalregister.gov/documents/2026/07/16/2026-14327/medicare-and-medicaid-programs-cy-2027-payment-policies-under-the-physician-fee-schedule-and-other", "start_page": 43842, "end_page": 44557, "fr_volume": 91} +{"item_key": "78F558TF", "p_id": 2818, "page": 73431, "ordinal": 10, "text": "Section 1833(x)(2)(B) of the Act (as added by section 5501(a)(2)(B) of the ACA) defines primary care services as those services identified by the following HCPCS codes as of January 1, 2009 (and as subsequently modified by the Secretary, as applicable):", "title": "Medicare Program; CY 2011 PFS Final Rule", "date_published": "2010-11-29", "document_number": "2010-27969", "html_url": "https://www.federalregister.gov/documents/2010/11/29/2010-27969/medicare-program-payment-policies-under-the-physician-fee-schedule-and-other-revisions-to-part-b-for", "start_page": 73170, "end_page": 73860, "fr_volume": 75} +{"item_key": "78F558TF", "p_id": 2819, "page": 73431, "ordinal": 11, "text": "99201 through 99215 for new and established patient office or other outpatient E/M visits;", "title": "Medicare Program; CY 2011 PFS Final Rule", "date_published": "2010-11-29", "document_number": "2010-27969", "html_url": "https://www.federalregister.gov/documents/2010/11/29/2010-27969/medicare-program-payment-policies-under-the-physician-fee-schedule-and-other-revisions-to-part-b-for", "start_page": 73170, "end_page": 73860, "fr_volume": 75} +{"item_key": "78F558TF", "p_id": 2820, "page": 73431, "ordinal": 12, "text": "99304 through 99340 for initial, subsequent, discharge, and other nursing facility E/M services; new and ( printed page 73432) established patient domiciliary, rest home (eg, boarding home), or custodial care E/M services; and domiciliary, rest home (eg, assisted living facility), or home care plan oversight services; and", "title": "Medicare Program; CY 2011 PFS Final Rule", "date_published": "2010-11-29", "document_number": "2010-27969", "html_url": "https://www.federalregister.gov/documents/2010/11/29/2010-27969/medicare-program-payment-policies-under-the-physician-fee-schedule-and-other-revisions-to-part-b-for", "start_page": 73170, "end_page": 73860, "fr_volume": 75} +{"item_key": "78F558TF", "p_id": 2821, "page": 73432, "ordinal": 1, "text": "99341 through 99350 for new and established patient home E/M visits. These codes are displayed in Table 66. All of these codes remain active in CY 2011 and there are no other codes used to describe these services.", "title": "Medicare Program; CY 2011 PFS Final Rule", "date_published": "2010-11-29", "document_number": "2010-27969", "html_url": "https://www.federalregister.gov/documents/2010/11/29/2010-27969/medicare-program-payment-policies-under-the-physician-fee-schedule-and-other-revisions-to-part-b-for", "start_page": 73170, "end_page": 73860, "fr_volume": 75} +{"item_key": "GD84NJ2Y", "p_id": 8, "page": 55246, "ordinal": 8, "text": "Mail written comments (1 original and 2 copies) to the following address: Centers for Medicare & Medicaid Services, Department of Health and Human Services, Attention: CMS-1169-FC, P.O. Box 8013, Baltimore, MD 21244-8013.", "title": "Medicare Program; CY 2002 PFS Final Rule", "date_published": "2001-11-01", "document_number": "01-27275", "html_url": "https://www.federalregister.gov/documents/2001/11/01/01-27275/medicare-program-revisions-to-payment-policies-and-five-year-review-of-and-adjustments-to-the", "start_page": 55246, "end_page": 55503, "fr_volume": 66} diff --git a/tests/pfs/fixtures/home_visits_rvu.csv b/tests/pfs/fixtures/home_visits_rvu.csv new file mode 100644 index 0000000..db14667 --- /dev/null +++ b/tests/pfs/fixtures/home_visits_rvu.csv @@ -0,0 +1,217 @@ +hcpcs,mod,description,status_code,not_used_for_medicare,work_rvu,non_fac_pe_rvu,fac_pe_rvu,mp_rvu,non_fac_total,fac_total,pctc_ind,glob_days,pre_op,intra_op,post_op,mult_proc,bilat_surg,asst_surg,co_surg,team_surg,endo_base,conv_factor,physician_supervision,calc_flag,diag_imaging_family,non_fac_pe_used_for_opps,fac_pe_used_for_opps,mp_used_for_opps,year,cms_rule_id +99324,,,A,,1.01,0.48,0.48,0.06,1.55,1.55,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.9335,09,0,99,0.0,0.0,0.0,2015, +99325,,,A,,1.52,0.64,0.64,0.1,2.26,2.26,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.9335,09,0,99,0.0,0.0,0.0,2015, +99326,,,A,,2.63,1.12,1.12,0.16,3.91,3.91,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.9335,09,0,99,0.0,0.0,0.0,2015, +99327,,,A,,3.46,1.55,1.55,0.21,5.22,5.22,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.9335,09,0,99,0.0,0.0,0.0,2015, +99328,,,A,,4.09,1.76,1.76,0.26,6.11,6.11,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.9335,09,0,99,0.0,0.0,0.0,2015, +99334,,,A,,1.07,0.56,0.56,0.06,1.69,1.69,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.9335,09,0,99,0.0,0.0,0.0,2015, +99335,,,A,,1.72,0.85,0.85,0.1,2.67,2.67,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.9335,09,0,99,0.0,0.0,0.0,2015, +99336,,,A,,2.46,1.17,1.17,0.15,3.78,3.78,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.9335,09,0,99,0.0,0.0,0.0,2015, +99337,,,A,,3.58,1.62,1.62,0.21,5.41,5.41,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.9335,09,0,99,0.0,0.0,0.0,2015, +99339,,,B,+,1.25,0.86,0.86,0.09,2.2,2.2,9,XXX,0.0,0.0,0.0,9,9,9,9,9,,35.9335,09,0,99,0.0,0.0,0.0,2015, +99340,,,B,+,1.8,1.15,1.15,0.12,3.07,3.07,9,XXX,0.0,0.0,0.0,9,9,9,9,9,,35.9335,09,0,99,0.0,0.0,0.0,2015, +99341,,,A,,1.01,0.47,0.47,0.06,1.54,1.54,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.9335,09,0,99,0.0,0.0,0.0,2015, +99342,,,A,,1.52,0.61,0.61,0.11,2.24,2.24,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.9335,09,0,99,0.0,0.0,0.0,2015, +99343,,,A,,2.53,0.95,0.95,0.17,3.65,3.65,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.9335,09,0,99,0.0,0.0,0.0,2015, +99344,,,A,,3.38,1.52,1.52,0.22,5.12,5.12,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.9335,09,0,99,0.0,0.0,0.0,2015, +99345,,,A,,4.09,1.84,1.84,0.27,6.2,6.2,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.9335,09,0,99,0.0,0.0,0.0,2015, +99347,,,A,,1.0,0.5,0.5,0.06,1.56,1.56,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.9335,09,0,99,0.0,0.0,0.0,2015, +99348,,,A,,1.56,0.7,0.7,0.1,2.36,2.36,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.9335,09,0,99,0.0,0.0,0.0,2015, +99349,,,A,,2.33,1.12,1.12,0.15,3.6,3.6,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.9335,09,0,99,0.0,0.0,0.0,2015, +99350,,,A,,3.28,1.49,1.49,0.21,4.98,4.98,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.9335,09,0,99,0.0,0.0,0.0,2015, +99324,,,A,,1.01,0.48,0.48,0.07,1.56,1.56,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.8043,09,0,99,0.0,0.0,0.0,2016, +99325,,,A,,1.52,0.65,0.65,0.1,2.27,2.27,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.8043,09,0,99,0.0,0.0,0.0,2016, +99326,,,A,,2.63,1.12,1.12,0.17,3.92,3.92,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.8043,09,0,99,0.0,0.0,0.0,2016, +99327,,,A,,3.46,1.55,1.55,0.22,5.23,5.23,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.8043,09,0,99,0.0,0.0,0.0,2016, +99328,,,A,,4.09,1.76,1.76,0.26,6.11,6.11,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.8043,09,0,99,0.0,0.0,0.0,2016, +99334,,,A,,1.07,0.56,0.56,0.07,1.7,1.7,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.8043,09,0,99,0.0,0.0,0.0,2016, +99335,,,A,,1.72,0.85,0.85,0.11,2.68,2.68,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.8043,09,0,99,0.0,0.0,0.0,2016, +99336,,,A,,2.46,1.17,1.17,0.16,3.79,3.79,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.8043,09,0,99,0.0,0.0,0.0,2016, +99337,,,A,,3.58,1.61,1.61,0.24,5.43,5.43,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.8043,09,0,99,0.0,0.0,0.0,2016, +99339,,,B,+,1.25,0.86,0.86,0.07,2.18,2.18,9,XXX,0.0,0.0,0.0,9,9,9,9,9,,35.8043,09,0,99,0.0,0.0,0.0,2016, +99340,,,B,+,1.8,1.15,1.15,0.11,3.06,3.06,9,XXX,0.0,0.0,0.0,9,9,9,9,9,,35.8043,09,0,99,0.0,0.0,0.0,2016, +99341,,,A,,1.01,0.47,0.47,0.07,1.55,1.55,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.8043,09,0,99,0.0,0.0,0.0,2016, +99342,,,A,,1.52,0.61,0.61,0.1,2.23,2.23,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.8043,09,0,99,0.0,0.0,0.0,2016, +99343,,,A,,2.53,0.96,0.96,0.17,3.66,3.66,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.8043,09,0,99,0.0,0.0,0.0,2016, +99344,,,A,,3.38,1.52,1.52,0.23,5.13,5.13,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.8043,09,0,99,0.0,0.0,0.0,2016, +99345,,,A,,4.09,1.84,1.84,0.29,6.22,6.22,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.8043,09,0,99,0.0,0.0,0.0,2016, +99347,,,A,,1.0,0.49,0.49,0.07,1.56,1.56,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.8043,09,0,99,0.0,0.0,0.0,2016, +99348,,,A,,1.56,0.7,0.7,0.11,2.37,2.37,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.8043,09,0,99,0.0,0.0,0.0,2016, +99349,,,A,,2.33,1.12,1.12,0.16,3.61,3.61,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.8043,09,0,99,0.0,0.0,0.0,2016, +99350,,,A,,3.28,1.5,1.5,0.23,5.01,5.01,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.8043,09,0,99,0.0,0.0,0.0,2016, +99324,,,A,,1.01,0.48,0.48,0.07,1.56,1.56,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.8887,09,0,99,0.0,0.0,0.0,2017, +99325,,,A,,1.52,0.65,0.65,0.1,2.27,2.27,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.8887,09,0,99,0.0,0.0,0.0,2017, +99326,,,A,,2.63,1.14,1.14,0.17,3.94,3.94,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.8887,09,0,99,0.0,0.0,0.0,2017, +99327,,,A,,3.46,1.57,1.57,0.22,5.25,5.25,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.8887,09,0,99,0.0,0.0,0.0,2017, +99328,,,A,,4.09,1.79,1.79,0.27,6.15,6.15,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.8887,09,0,99,0.0,0.0,0.0,2017, +99334,,,A,,1.07,0.56,0.56,0.07,1.7,1.7,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.8887,09,0,99,0.0,0.0,0.0,2017, +99335,,,A,,1.72,0.85,0.85,0.11,2.68,2.68,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.8887,09,0,99,0.0,0.0,0.0,2017, +99336,,,A,,2.46,1.19,1.19,0.16,3.81,3.81,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.8887,09,0,99,0.0,0.0,0.0,2017, +99337,,,A,,3.58,1.63,1.63,0.24,5.45,5.45,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.8887,09,0,99,0.0,0.0,0.0,2017, +99339,,,B,+,1.25,0.86,0.86,0.07,2.18,2.18,9,XXX,0.0,0.0,0.0,9,9,9,9,9,,35.8887,09,0,99,0.0,0.0,0.0,2017, +99340,,,B,+,1.8,1.15,1.15,0.11,3.06,3.06,9,XXX,0.0,0.0,0.0,9,9,9,9,9,,35.8887,09,0,99,0.0,0.0,0.0,2017, +99341,,,A,,1.01,0.47,0.47,0.07,1.55,1.55,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.8887,09,0,99,0.0,0.0,0.0,2017, +99342,,,A,,1.52,0.62,0.62,0.1,2.24,2.24,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.8887,09,0,99,0.0,0.0,0.0,2017, +99343,,,A,,2.53,0.98,0.98,0.17,3.68,3.68,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.8887,09,0,99,0.0,0.0,0.0,2017, +99344,,,A,,3.38,1.55,1.55,0.23,5.16,5.16,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.8887,09,0,99,0.0,0.0,0.0,2017, +99345,,,A,,4.09,1.87,1.87,0.29,6.25,6.25,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.8887,09,0,99,0.0,0.0,0.0,2017, +99347,,,A,,1.0,0.49,0.49,0.07,1.56,1.56,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.8887,09,0,99,0.0,0.0,0.0,2017, +99348,,,A,,1.56,0.71,0.71,0.11,2.38,2.38,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.8887,09,0,99,0.0,0.0,0.0,2017, +99349,,,A,,2.33,1.14,1.14,0.16,3.63,3.63,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.8887,09,0,99,0.0,0.0,0.0,2017, +99350,,,A,,3.28,1.52,1.52,0.23,5.03,5.03,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.8887,09,0,99,0.0,0.0,0.0,2017, +99324,,,A,,1.01,0.48,0.48,0.07,1.56,1.56,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.9996,09,0,99,0.0,0.0,0.0,2018, +99325,,,A,,1.52,0.65,0.65,0.1,2.27,2.27,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.9996,09,0,99,0.0,0.0,0.0,2018, +99326,,,A,,2.63,1.14,1.14,0.17,3.94,3.94,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.9996,09,0,99,0.0,0.0,0.0,2018, +99327,,,A,,3.46,1.58,1.58,0.23,5.27,5.27,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.9996,09,0,99,0.0,0.0,0.0,2018, +99328,,,A,,4.09,1.82,1.82,0.26,6.17,6.17,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.9996,09,0,99,0.0,0.0,0.0,2018, +99334,,,A,,1.07,0.56,0.56,0.07,1.7,1.7,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.9996,09,0,99,0.0,0.0,0.0,2018, +99335,,,A,,1.72,0.85,0.85,0.11,2.68,2.68,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.9996,09,0,99,0.0,0.0,0.0,2018, +99336,,,A,,2.46,1.2,1.2,0.17,3.83,3.83,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.9996,09,0,99,0.0,0.0,0.0,2018, +99337,,,A,,3.58,1.65,1.65,0.24,5.47,5.47,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.9996,09,0,99,0.0,0.0,0.0,2018, +99339,,,B,+,1.25,0.87,0.87,0.07,2.19,2.19,9,XXX,0.0,0.0,0.0,9,9,9,9,9,,35.9996,09,0,99,0.0,0.0,0.0,2018, +99340,,,B,+,1.8,1.16,1.16,0.11,3.07,3.07,9,XXX,0.0,0.0,0.0,9,9,9,9,9,,35.9996,09,0,99,0.0,0.0,0.0,2018, +99341,,,A,,1.01,0.47,0.47,0.07,1.55,1.55,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.9996,09,0,99,0.0,0.0,0.0,2018, +99342,,,A,,1.52,0.62,0.62,0.11,2.25,2.25,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.9996,09,0,99,0.0,0.0,0.0,2018, +99343,,,A,,2.53,0.98,0.98,0.18,3.69,3.69,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.9996,09,0,99,0.0,0.0,0.0,2018, +99344,,,A,,3.38,1.56,1.56,0.23,5.17,5.17,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.9996,09,0,99,0.0,0.0,0.0,2018, +99345,,,A,,4.09,1.9,1.9,0.29,6.28,6.28,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.9996,09,0,99,0.0,0.0,0.0,2018, +99347,,,A,,1.0,0.49,0.49,0.07,1.56,1.56,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.9996,09,0,99,0.0,0.0,0.0,2018, +99348,,,A,,1.56,0.71,0.71,0.11,2.38,2.38,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.9996,09,0,99,0.0,0.0,0.0,2018, +99349,,,A,,2.33,1.15,1.15,0.16,3.64,3.64,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.9996,09,0,99,0.0,0.0,0.0,2018, +99350,,,A,,3.28,1.55,1.55,0.23,5.06,5.06,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,35.9996,09,0,99,0.0,0.0,0.0,2018, +99324,,,A,,1.01,0.48,0.48,0.07,1.56,1.56,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,36.0391,09,0,99,0.0,0.0,0.0,2019, +99325,,,A,,1.52,0.64,0.64,0.1,2.26,2.26,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,36.0391,09,0,99,0.0,0.0,0.0,2019, +99326,,,A,,2.63,1.12,1.12,0.17,3.92,3.92,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,36.0391,09,0,99,0.0,0.0,0.0,2019, +99327,,,A,,3.46,1.57,1.57,0.23,5.26,5.26,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,36.0391,09,0,99,0.0,0.0,0.0,2019, +99328,,,A,,4.09,1.83,1.83,0.27,6.19,6.19,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,36.0391,09,0,99,0.0,0.0,0.0,2019, +99334,,,A,,1.07,0.56,0.56,0.07,1.7,1.7,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,36.0391,09,0,99,0.0,0.0,0.0,2019, +99335,,,A,,1.72,0.85,0.85,0.11,2.68,2.68,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,36.0391,09,0,99,0.0,0.0,0.0,2019, +99336,,,A,,2.46,1.19,1.19,0.17,3.82,3.82,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,36.0391,09,0,99,0.0,0.0,0.0,2019, +99337,,,A,,3.58,1.65,1.65,0.24,5.47,5.47,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,36.0391,09,0,99,0.0,0.0,0.0,2019, +99339,,,B,+,1.25,0.85,0.85,0.07,2.17,2.17,9,XXX,0.0,0.0,0.0,9,9,9,9,9,,36.0391,09,0,99,0.0,0.0,0.0,2019, +99340,,,B,+,1.8,1.14,1.14,0.11,3.05,3.05,9,XXX,0.0,0.0,0.0,9,9,9,9,9,,36.0391,09,0,99,0.0,0.0,0.0,2019, +99341,,,A,,1.01,0.48,0.48,0.07,1.56,1.56,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,36.0391,09,0,99,0.0,0.0,0.0,2019, +99342,,,A,,1.52,0.62,0.62,0.11,2.25,2.25,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,36.0391,09,0,99,0.0,0.0,0.0,2019, +99343,,,A,,2.53,0.96,0.96,0.18,3.67,3.67,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,36.0391,09,0,99,0.0,0.0,0.0,2019, +99344,,,A,,3.38,1.53,1.53,0.23,5.14,5.14,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,36.0391,09,0,99,0.0,0.0,0.0,2019, +99345,,,A,,4.09,1.88,1.88,0.28,6.25,6.25,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,36.0391,09,0,99,0.0,0.0,0.0,2019, +99347,,,A,,1.0,0.49,0.49,0.07,1.56,1.56,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,36.0391,09,0,99,0.0,0.0,0.0,2019, +99348,,,A,,1.56,0.7,0.7,0.11,2.37,2.37,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,36.0391,09,0,99,0.0,0.0,0.0,2019, +99349,,,A,,2.33,1.15,1.15,0.16,3.64,3.64,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,36.0391,09,0,99,0.0,0.0,0.0,2019, +99350,,,A,,3.28,1.54,1.54,0.23,5.05,5.05,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,36.0391,09,0,99,0.0,0.0,0.0,2019, +99324,,,A,,1.01,0.48,0.48,0.05,1.54,1.54,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,36.0896,09,0,99,0.0,0.0,0.0,2020, +99325,,,A,,1.52,0.64,0.64,0.08,2.24,2.24,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,36.0896,09,0,99,0.0,0.0,0.0,2020, +99326,,,A,,2.63,1.14,1.14,0.13,3.9,3.9,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,36.0896,09,0,99,0.0,0.0,0.0,2020, +99327,,,A,,3.46,1.59,1.59,0.19,5.24,5.24,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,36.0896,09,0,99,0.0,0.0,0.0,2020, +99328,,,A,,4.09,1.86,1.86,0.25,6.2,6.2,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,36.0896,09,0,99,0.0,0.0,0.0,2020, +99334,,,A,,1.07,0.57,0.57,0.06,1.7,1.7,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,36.0896,09,0,99,0.0,0.0,0.0,2020, +99335,,,A,,1.72,0.88,0.88,0.09,2.69,2.69,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,36.0896,09,0,99,0.0,0.0,0.0,2020, +99336,,,A,,2.46,1.21,1.21,0.13,3.8,3.8,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,36.0896,09,0,99,0.0,0.0,0.0,2020, +99337,,,A,,3.58,1.68,1.68,0.22,5.48,5.48,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,36.0896,09,0,99,0.0,0.0,0.0,2020, +99339,,,B,+,1.25,0.85,0.85,0.09,2.19,2.19,9,XXX,0.0,0.0,0.0,9,9,9,9,9,,36.0896,09,0,99,0.0,0.0,0.0,2020, +99340,,,B,+,1.8,1.12,1.12,0.13,3.05,3.05,9,XXX,0.0,0.0,0.0,9,9,9,9,9,,36.0896,09,0,99,0.0,0.0,0.0,2020, +99341,,,A,,1.01,0.48,0.48,0.05,1.54,1.54,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,36.0896,09,0,99,0.0,0.0,0.0,2020, +99342,,,A,,1.52,0.61,0.61,0.08,2.21,2.21,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,36.0896,09,0,99,0.0,0.0,0.0,2020, +99343,,,A,,2.53,0.97,0.97,0.13,3.63,3.63,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,36.0896,09,0,99,0.0,0.0,0.0,2020, +99344,,,A,,3.38,1.55,1.55,0.22,5.15,5.15,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,36.0896,09,0,99,0.0,0.0,0.0,2020, +99345,,,A,,4.09,1.9,1.9,0.28,6.27,6.27,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,36.0896,09,0,99,0.0,0.0,0.0,2020, +99347,,,A,,1.0,0.49,0.49,0.05,1.54,1.54,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,36.0896,09,0,99,0.0,0.0,0.0,2020, +99348,,,A,,1.56,0.72,0.72,0.09,2.37,2.37,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,36.0896,09,0,99,0.0,0.0,0.0,2020, +99349,,,A,,2.33,1.17,1.17,0.13,3.63,3.63,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,36.0896,09,0,99,0.0,0.0,0.0,2020, +99350,,,A,,3.28,1.56,1.56,0.22,5.06,5.06,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,36.0896,09,0,99,0.0,0.0,0.0,2020, +99324,,,A,,1.01,0.49,0.49,0.05,1.55,1.55,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,34.8931,09,0,99,0.0,0.0,0.0,2021, +99325,,,A,,1.52,0.66,0.66,0.09,2.27,2.27,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,34.8931,09,0,99,0.0,0.0,0.0,2021, +99326,,,A,,2.63,1.2,1.2,0.14,3.97,3.97,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,34.8931,09,0,99,0.0,0.0,0.0,2021, +99327,,,A,,3.46,1.66,1.66,0.2,5.32,5.32,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,34.8931,09,0,99,0.0,0.0,0.0,2021, +99328,,,A,,4.09,1.92,1.92,0.25,6.26,6.26,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,34.8931,09,0,99,0.0,0.0,0.0,2021, +99334,,,A,,1.07,0.6,0.6,0.05,1.72,1.72,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,34.8931,09,0,99,0.0,0.0,0.0,2021, +99335,,,A,,1.72,0.92,0.92,0.1,2.74,2.74,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,34.8931,09,0,99,0.0,0.0,0.0,2021, +99336,,,A,,2.46,1.27,1.27,0.15,3.88,3.88,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,34.8931,09,0,99,0.0,0.0,0.0,2021, +99337,,,A,,3.58,1.76,1.76,0.21,5.55,5.55,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,34.8931,09,0,99,0.0,0.0,0.0,2021, +99339,,,B,+,1.25,0.87,0.87,0.1,2.22,2.22,9,XXX,0.0,0.0,0.0,9,9,9,9,9,,34.8931,09,0,99,0.0,0.0,0.0,2021, +99340,,,B,+,1.8,1.15,1.15,0.15,3.1,3.1,9,XXX,0.0,0.0,0.0,9,9,9,9,9,,34.8931,09,0,99,0.0,0.0,0.0,2021, +99341,,,A,,1.01,0.5,0.5,0.05,1.56,1.56,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,34.8931,09,0,99,0.0,0.0,0.0,2021, +99342,,,A,,1.52,0.62,0.62,0.06,2.2,2.2,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,34.8931,09,0,99,0.0,0.0,0.0,2021, +99343,,,A,,2.53,0.98,0.98,0.13,3.64,3.64,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,34.8931,09,0,99,0.0,0.0,0.0,2021, +99344,,,A,,3.38,1.6,1.6,0.21,5.19,5.19,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,34.8931,09,0,99,0.0,0.0,0.0,2021, +99345,,,A,,4.09,1.92,1.92,0.31,6.32,6.32,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,34.8931,09,0,99,0.0,0.0,0.0,2021, +99347,,,A,,1.0,0.52,0.52,0.05,1.57,1.57,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,34.8931,09,0,99,0.0,0.0,0.0,2021, +99348,,,A,,1.56,0.75,0.75,0.09,2.4,2.4,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,34.8931,09,0,99,0.0,0.0,0.0,2021, +99349,,,A,,2.33,1.22,1.22,0.15,3.7,3.7,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,34.8931,09,0,99,0.0,0.0,0.0,2021, +99350,,,A,,3.28,1.62,1.62,0.22,5.12,5.12,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,34.8931,09,0,99,0.0,0.0,0.0,2021, +99324,,,A,,1.01,0.5,0.5,0.05,1.56,1.56,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,34.6062,09,0,99,0.0,0.0,0.0,2022, +99325,,,A,,1.52,0.67,0.67,0.09,2.28,2.28,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,34.6062,09,0,99,0.0,0.0,0.0,2022, +99326,,,A,,2.63,1.2,1.2,0.12,3.95,3.95,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,34.6062,09,0,99,0.0,0.0,0.0,2022, +99327,,,A,,3.46,1.66,1.66,0.2,5.32,5.32,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,34.6062,09,0,99,0.0,0.0,0.0,2022, +99328,,,A,,4.09,1.92,1.92,0.25,6.26,6.26,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,34.6062,09,0,99,0.0,0.0,0.0,2022, +99334,,,A,,1.07,0.61,0.61,0.07,1.75,1.75,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,34.6062,09,0,99,0.0,0.0,0.0,2022, +99335,,,A,,1.72,0.93,0.93,0.1,2.75,2.75,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,34.6062,09,0,99,0.0,0.0,0.0,2022, +99336,,,A,,2.46,1.29,1.29,0.14,3.89,3.89,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,34.6062,09,0,99,0.0,0.0,0.0,2022, +99337,,,A,,3.58,1.77,1.77,0.22,5.57,5.57,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,34.6062,09,0,99,0.0,0.0,0.0,2022, +99339,,,B,+,1.25,0.87,0.87,0.1,2.22,2.22,9,XXX,0.0,0.0,0.0,9,9,9,9,9,,34.6062,09,0,99,0.0,0.0,0.0,2022, +99340,,,B,+,1.8,1.17,1.17,0.14,3.11,3.11,9,XXX,0.0,0.0,0.0,9,9,9,9,9,,34.6062,09,0,99,0.0,0.0,0.0,2022, +99341,,,A,,1.01,0.5,0.5,0.05,1.56,1.56,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,34.6062,09,0,99,0.0,0.0,0.0,2022, +99342,,,A,,1.52,0.62,0.62,0.08,2.22,2.22,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,34.6062,09,0,99,0.0,0.0,0.0,2022, +99343,,,A,,2.53,0.96,0.96,0.12,3.61,3.61,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,34.6062,09,0,99,0.0,0.0,0.0,2022, +99344,,,A,,3.38,1.6,1.6,0.22,5.2,5.2,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,34.6062,09,0,99,0.0,0.0,0.0,2022, +99345,,,A,,4.09,1.93,1.93,0.28,6.3,6.3,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,34.6062,09,0,99,0.0,0.0,0.0,2022, +99347,,,A,,1.0,0.53,0.53,0.05,1.58,1.58,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,34.6062,09,0,99,0.0,0.0,0.0,2022, +99348,,,A,,1.56,0.75,0.75,0.09,2.4,2.4,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,34.6062,09,0,99,0.0,0.0,0.0,2022, +99349,,,A,,2.33,1.23,1.23,0.14,3.7,3.7,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,34.6062,09,0,99,0.0,0.0,0.0,2022, +99350,,,A,,3.28,1.62,1.62,0.23,5.13,5.13,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,34.6062,09,0,99,0.0,0.0,0.0,2022, +99341,,,A,,1.0,0.4,0.4,0.04,1.44,1.44,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,33.8872,09,0,99,0.0,0.0,0.0,2023, +99342,,,A,,1.65,0.57,0.57,0.08,2.3,2.3,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,33.8872,09,0,99,0.0,0.0,0.0,2023, +99344,,,A,,2.87,1.2,1.2,0.18,4.25,4.25,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,33.8872,09,0,99,0.0,0.0,0.0,2023, +99345,,,A,,3.88,1.85,1.85,0.25,5.98,5.98,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,33.8872,09,0,99,0.0,0.0,0.0,2023, +99347,,,A,,0.9,0.38,0.38,0.04,1.32,1.32,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,33.8872,09,0,99,0.0,0.0,0.0,2023, +99348,,,A,,1.5,0.67,0.67,0.08,2.25,2.25,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,33.8872,09,0,99,0.0,0.0,0.0,2023, +99349,,,A,,2.44,1.16,1.16,0.17,3.77,3.77,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,33.8872,09,0,99,0.0,0.0,0.0,2023, +99350,,,A,,3.6,1.65,1.65,0.25,5.5,5.5,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,33.8872,09,0,99,0.0,0.0,0.0,2023, +99341,,,A,,1.0,0.42,0.42,0.05,1.47,1.47,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,33.2875,09,0,99,0.0,0.0,0.0,2024, +99342,,,A,,1.65,0.6,0.6,0.08,2.33,2.33,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,33.2875,09,0,99,0.0,0.0,0.0,2024, +99344,,,A,,2.87,1.2,1.2,0.16,4.23,4.23,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,33.2875,09,0,99,0.0,0.0,0.0,2024, +99345,,,A,,3.88,1.88,1.88,0.25,6.01,6.01,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,33.2875,09,0,99,0.0,0.0,0.0,2024, +99347,,,A,,0.9,0.4,0.4,0.05,1.35,1.35,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,33.2875,09,0,99,0.0,0.0,0.0,2024, +99348,,,A,,1.5,0.7,0.7,0.08,2.28,2.28,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,33.2875,09,0,99,0.0,0.0,0.0,2024, +99349,,,A,,2.44,1.19,1.19,0.16,3.79,3.79,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,33.2875,09,0,99,0.0,0.0,0.0,2024, +99350,,,A,,3.6,1.68,1.68,0.24,5.52,5.52,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,33.2875,09,0,99,0.0,0.0,0.0,2024, +99341,,,A,,1.0,0.43,0.43,0.04,1.47,1.47,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,32.3465,09,0,99,0.0,0.0,0.0,2025, +99342,,,A,,1.65,0.62,0.62,0.07,2.34,2.34,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,32.3465,09,0,99,0.0,0.0,0.0,2025, +99344,,,A,,2.87,1.2,1.2,0.16,4.23,4.23,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,32.3465,09,0,99,0.0,0.0,0.0,2025, +99345,,,A,,3.88,1.86,1.86,0.25,5.99,5.99,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,32.3465,09,0,99,0.0,0.0,0.0,2025, +99347,,,A,,0.9,0.41,0.41,0.04,1.35,1.35,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,32.3465,09,0,99,0.0,0.0,0.0,2025, +99348,,,A,,1.5,0.71,0.71,0.08,2.29,2.29,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,32.3465,09,0,99,0.0,0.0,0.0,2025, +99349,,,A,,2.44,1.19,1.19,0.16,3.79,3.79,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,32.3465,09,0,99,0.0,0.0,0.0,2025, +99350,,,A,,3.6,1.67,1.67,0.23,5.5,5.5,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,32.3465,09,0,99,0.0,0.0,0.0,2025, +99341,,,A,,1.0,0.43,0.43,0.04,1.47,1.47,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,33.4009,09,0,99,0.0,0.0,0.0,2026, +99342,,,A,,1.65,0.64,0.64,0.07,2.36,2.36,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,33.4009,09,0,99,0.0,0.0,0.0,2026, +99344,,,A,,2.87,1.36,1.36,0.16,4.39,4.39,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,33.4009,09,0,99,0.0,0.0,0.0,2026, +99345,,,A,,3.88,2.16,2.16,0.25,6.29,6.29,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,33.4009,09,0,99,0.0,0.0,0.0,2026, +99347,,,A,,0.9,0.44,0.44,0.04,1.38,1.38,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,33.4009,09,0,99,0.0,0.0,0.0,2026, +99348,,,A,,1.5,0.79,0.79,0.07,2.36,2.36,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,33.4009,09,0,99,0.0,0.0,0.0,2026, +99349,,,A,,2.44,1.36,1.36,0.16,3.96,3.96,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,33.4009,09,0,99,0.0,0.0,0.0,2026, +99350,,,A,,3.6,1.94,1.94,0.24,5.78,5.78,0,XXX,0.0,0.0,0.0,0,0,0,0,0,,33.4009,09,0,99,0.0,0.0,0.0,2026, +99341,,,A,,1.0,0.46,,0.03,1.49,,,XXX,,,,,,,,,,,,,,,,,2027, +99342,,,A,,1.65,0.68,,0.09,2.42,,,XXX,,,,,,,,,,,,,,,,,2027, +99344,,,A,,2.87,1.38,,0.16,4.41,,,XXX,,,,,,,,,,,,,,,,,2027, +99345,,,A,,3.88,2.06,,0.25,6.19,,,XXX,,,,,,,,,,,,,,,,,2027, +99347,,,A,,0.9,0.47,,0.05,1.42,,,XXX,,,,,,,,,,,,,,,,,2027, +99348,,,A,,1.5,0.81,,0.09,2.4,,,XXX,,,,,,,,,,,,,,,,,2027, +99349,,,A,,2.44,1.29,,0.15,3.88,,,XXX,,,,,,,,,,,,,,,,,2027, +99350,,,A,,3.6,1.85,,0.24,5.69,,,XXX,,,,,,,,,,,,,,,,,2027, +99341,,,A,,1.0,0.43,,0.04,,,,,,,,,,,,,,,,,,,,,,CMS-1832-P +99342,,,A,,1.65,0.64,,0.06,,,,,,,,,,,,,,,,,,,,,,CMS-1832-P +99344,,,A,,2.87,1.37,,0.18,,,,,,,,,,,,,,,,,,,,,,CMS-1832-P +99345,,,A,,3.88,2.14,,0.27,,,,,,,,,,,,,,,,,,,,,,CMS-1832-P +99347,,,A,,0.9,0.44,,0.04,,,,,,,,,,,,,,,,,,,,,,CMS-1832-P +99348,,,A,,1.5,0.78,,0.07,,,,,,,,,,,,,,,,,,,,,,CMS-1832-P +99349,,,A,,2.44,1.35,,0.17,,,,,,,,,,,,,,,,,,,,,,CMS-1832-P +99350,,,A,,3.6,1.93,,0.25,,,,,,,,,,,,,,,,,,,,,,CMS-1832-P +99341,,,A,,1.0,0.46,,0.05,,,,,,,,,,,,,,,,,,,,,,CMS-1848-P +99342,,,A,,1.65,0.68,,0.07,,,,,,,,,,,,,,,,,,,,,,CMS-1848-P +99344,,,A,,2.87,1.39,,0.17,,,,,,,,,,,,,,,,,,,,,,CMS-1848-P +99345,,,A,,3.88,2.05,,0.26,,,,,,,,,,,,,,,,,,,,,,CMS-1848-P +99347,,,A,,0.9,0.47,,0.05,,,,,,,,,,,,,,,,,,,,,,CMS-1848-P +99348,,,A,,1.5,0.82,,0.09,,,,,,,,,,,,,,,,,,,,,,CMS-1848-P +99349,,,A,,2.44,1.29,,0.15,,,,,,,,,,,,,,,,,,,,,,CMS-1848-P +99350,,,A,,3.6,1.85,,0.25,,,,,,,,,,,,,,,,,,,,,,CMS-1848-P diff --git a/tests/pfs/home_visits_fixture.py b/tests/pfs/home_visits_fixture.py new file mode 100644 index 0000000..90a939b --- /dev/null +++ b/tests/pfs/home_visits_fixture.py @@ -0,0 +1,750 @@ +"""The HOME-VISITS proof family as a self-contained fixture (dossier task 13). + +``home_fixture`` returns ``(con, store, family, ask)``: + +* ``store`` — a ``Store(":memory:")`` holding the Federal Register paragraphs + of ``fixtures/home_visits_fr.jsonl`` (public-domain FR text; the CPT + descriptors CMS printed inside a few paragraphs are replaced by + ``[CPT descriptor omitted]``), their rule items and anchor maps, three + regulations.gov comment items whose bib titles name a person ("Jane Doe: + CMS-2022-0113-0001" style) and the CY2023 docket; +* ``con`` — a ``:memory:`` DuckDB with ``ensure_tables``, ``pfs.rvu`` and + ``pfs.rvu_proposed`` from ``fixtures/home_visits_rvu.csv`` (descriptors + blank), and the rows of Tasks 2-11 produced by running those tasks' + functions over the fixture: lineage (T2), valuation rounds from the FR + paragraphs and the CY2008 Table 14 (T4/T5), guidance and origin (T6), CMS's + Comment:/Response: summaries (T7), the stance roll-up (T9). Commenters + (T8), stance positions (T9), guideline facts (T9b), PSPS billing and + specialty impacts (T10) and roster seats (T11) need regulations.gov, the + licensed books, data.cms.gov or the AMA site, so their rows are written + directly through the tables' own dataclasses; +* ``family`` — ``load_curated()["HOME-VISITS"]``; +* ``ask`` — a fake ``JsonExtractor`` answering from canned replies keyed by a + fragment of the prompt (``FakeAsk``). +""" + +from __future__ import annotations + +import csv +import json +from contextlib import contextmanager +from pathlib import Path +from typing import Any, Mapping + +import duckdb +import pytest + +from bib.dockets import Docket +from bib.item import Rule, Source +from bib.store import Store +from pfs.cms_summaries import summaries +from pfs.codetables import ( + CommenterRow, + GuidelineFactRow, + ImpactRow, + PspsRow, + ReactionRow, + SeatRow, + StanceRow, + ensure_tables, + write_cms_summaries, + write_commenters, + write_events, + write_guidance, + write_guideline_facts, + write_origin, + write_psps, + write_reaction, + write_rounds, + write_seats, + write_specialty_impacts, + write_stances, +) +from pfs.curated import load_curated +from pfs.guidance import build as build_guidance +from pfs.lineage import lineage +from pfs.origin import family_origin +from pfs.rounds import family_rounds +from pfs.runlog import RunLog +from pfs.stance import rollup + +FIXTURES = Path(__file__).parent / "fixtures" +FR_PATH = FIXTURES / "home_visits_fr.jsonl" +RVU_PATH = FIXTURES / "home_visits_rvu.csv" + +DOCKET = "CMS-2022-0113" +FAMILY = "HOME-VISITS" + +#: CY2008 final rule Table 14 (72 FR 66361) for the family's rows: codes and +#: Federal Register numbers only, the descriptor column left blank +TABLE14 = """[[Page 66361]] + + Table 14.--Work RVU Revisions for Additional 5-Year Review Codes +-------------------------------------------------------------------------------------------------------------------------------------------------------- + Work RVUs + CPT/HCPCS code \\1\\ Mod Descriptor Proposed work requested by RUC rec 2008 work RVU Basis for decision + RVU commenters +-------------------------------------------------------------------------------------------------------------------------------------------------------- +99326................... ........... - 2.27 2.85 2.27 2.63 Refinement. +99343................... ........... - 2.27 2.65 2.27 2.53 Refinement. +99350................... ........... - 3.03 3.45 3.03 3.28 Refinement. +-------------------------------------------------------------------------------------------------------------------------------------------------------- +""" + + +class FakeAsk: + """A fake ``JsonExtractor``: ``ask(system, user, schema)`` returns the + canned reply whose key occurs in *user* (first match, in insertion + order), else ``default`` (a reply, or a callable of ``(system, user)``). + Every call is recorded in ``calls``.""" + + def __init__( + self, + replies: Mapping[str, Any] | None = None, + default: Any = None, + model: str = "fake-14b", + ) -> None: + self.replies = dict(replies or {}) + self.default = default + self.model = model + self.calls: list[tuple[str, str]] = [] + + def __call__(self, system: str, user: str, schema: Any) -> Any: + self.calls.append((system, user)) + for key, reply in self.replies.items(): + if key in user: + return reply(system, user) if callable(reply) else reply + if callable(self.default): + return self.default(system, user) + return self.default + + +def fr_rows() -> list[dict]: + return [json.loads(line) for line in FR_PATH.read_text().splitlines() if line] + + +def build_store(storage: Path) -> Store: + s = Store(":memory:", storage_dir=storage) + rows = fr_rows() + con = s._con() + seen: set[str] = set() + for r in rows: + if r["item_key"] in seen: + continue + seen.add(r["item_key"]) + s.create( + Rule( + key=r["item_key"], + title=r["title"], + date_published=r["date_published"], + document_number=r["document_number"], + ) + ) + con.execute( + "INSERT INTO fr_anchor_docs (item_key, document_number, html_url, " + "start_page, end_page, fr_volume) VALUES (?,?,?,?,?,?)", + ( + r["item_key"], + r["document_number"], + r["html_url"], + r["start_page"], + r["end_page"], + r["fr_volume"], + ), + ) + con.executemany( + "INSERT INTO fr_anchors (item_key, p_id, page, ordinal, text) " + "VALUES (?,?,?,?,?)", + [(r["item_key"], r["p_id"], r["page"], r["ordinal"], r["text"]) for r in rows], + ) + # three comment items whose bib titles carry a person's name: never the + # source of a name on the dossier (pfs.commenter is) + for n, person in enumerate(("Jane Doe", "John Roe", "Ann Poe"), 1): + cid = f"{DOCKET}-{n:04d}" + s.create( + Source( + key=f"CMT{n:05d}", + title=f"{person}: {cid}", + url=f"https://www.regulations.gov/comment/{cid}", + ) + ) + s.docket_upsert( + Docket(id=DOCKET, rule_cms_id="CMS-1770-P", comment_end_date="2022-09-06") + ) + s.docket_upsert( + Docket( + id="CMS-2025-0304", rule_cms_id="CMS-1832-P", comment_end_date="2025-09-12" + ) + ) + con.commit() + table = storage.parent / "07-5506.txt" + table.write_text(TABLE14) + s.attach_file("54GTKR5G", table) + return s + + +def load_rvu(con: Any) -> None: + with RVU_PATH.open() as f: + rows = list(csv.DictReader(f)) + cols = [c for c in rows[0] if c != "cms_rule_id"] + num = { + "work_rvu", + "non_fac_pe_rvu", + "fac_pe_rvu", + "mp_rvu", + "non_fac_total", + "fac_total", + "pre_op", + "intra_op", + "post_op", + "conv_factor", + } + + def typed(c: str) -> str: + if c == "year": + return "INTEGER" + return "DOUBLE" if c in num else "VARCHAR" + + con.execute( + "CREATE TABLE pfs.rvu (" + ", ".join(f"{c} {typed(c)}" for c in cols) + ")" + ) + con.execute( + "CREATE TABLE pfs.rvu_proposed (hcpcs VARCHAR, mod VARCHAR, description " + "VARCHAR, status_code VARCHAR, work_rvu DOUBLE, non_fac_pe_rvu DOUBLE, " + "fac_pe_rvu DOUBLE, mp_rvu DOUBLE, cms_rule_id VARCHAR)" + ) + + def val(c: str, v: str) -> Any: + if v == "": + return None + return int(v) if c == "year" else float(v) if c in num else v + + final = [r for r in rows if not r["cms_rule_id"]] + con.executemany( + f"INSERT INTO pfs.rvu VALUES ({','.join('?' * len(cols))})", + [[val(c, r[c]) for c in cols] for r in final], + ) + pcols = ( + "hcpcs", + "mod", + "description", + "status_code", + "work_rvu", + "non_fac_pe_rvu", + "fac_pe_rvu", + "mp_rvu", + "cms_rule_id", + ) + con.executemany( + "INSERT INTO pfs.rvu_proposed VALUES (?,?,?,?,?,?,?,?,?)", + [[val(c, r[c]) for c in pcols] for r in rows if r["cms_rule_id"]], + ) + + +# ── rows the fixture writes directly (no live source in tests) ──────── + +COMMENTERS = ( + # item_key, comment id, org_name, org_type, specialty, posted name + ("CMT00001", "0001", "", "individual_clinician", "FAMILY PRACTICE", "Mary Major"), + ( + "CMT00002", + "0002", + "American Academy of Home Care Medicine", + "specialty_society", + "INTERNAL MEDICINE", + "", + ), + ("CMT00003", "0003", "Fixture Health System", "health_system", "NONE", ""), + ("CMT00004", "0004", "", "individual", "", ""), + ( + "CMT00005", + "0005", + "American Academy of Family Physicians", + "specialty_society", + "FAMILY PRACTICE", + "", + ), + ("CMT00006", "0006", "Fixture Health Plan", "payer", "", ""), +) + +STANCES = ( + ("CMT00001", "valuation", "support"), + ("CMT00002", "valuation", "modify"), + ("CMT00002", "G0318", "support"), + ("CMT00003", "valuation", "oppose"), + ("CMT00004", "other", "unclear"), + ("CMT00005", "coding", "support"), +) + +#: the method's measurement as task 9c stamps it on the golden family +STANCE_EVAL = { + "cell": 0.817, + "recall": 0.792, + "direction": 0.737, + "n_items": 20, + "n_positions": 24, + "family": FAMILY, + "dockets": ["CMS-2025-0304", "CMS-2026-2377"], + "in_sample": False, + "generation": "stance-v5", + "in_sample_record": { + "cell": 0.82, + "recall": 0.407, + "direction": 0.818, + "n_items": 20, + "n_positions": 27, + "docket": DOCKET, + }, +} + + +def _commenter_rows() -> list[CommenterRow]: + return [ + CommenterRow( + item_key=key, + docket=DOCKET, + comment_id=f"{DOCKET}-{cid}", + org_name=org, + org_type=typ, + specialty=spec, + form_group="", + form_size=0, + basis="letterhead_model", + reg_category="", + extractor="model:fake-14b@identity-v5", + family=FAMILY, + submitter_name=name, + ) + for key, cid, org, typ, spec, name in COMMENTERS + ] + + +def _stance_rows() -> list[StanceRow]: + return [ + StanceRow( + family=FAMILY, + item_key=key, + docket=DOCKET, + event_key=f"{FAMILY}:2023:{slug}", + stance=stance, + reason="", + evidence="", + extractor="model:fake-32b@stance-v5", + ) + for key, slug, stance in STANCES + ] + + +def _reaction_rows(stances: list[StanceRow]) -> list[ReactionRow]: + order = [f"{FAMILY}:2023:{s}" for s in ("valuation", "coding", "G0318", "other")] + base = ReactionRow(FAMILY, DOCKET, "docket", 2022, 6, 24341, 0, 0, 0, 0, "[]") + classified = rollup(stances, base=base, order=order, n_commenters=6) + classified = ReactionRow( + **{ + **classified.__dict__, + "stance_method": "stance-v5:fake-32b", + "stance_eval": json.dumps(STANCE_EVAL), + } + ) + # a docket with commenters but no classification yet: NULL n_classified + pending = ReactionRow( + FAMILY, "CMS-2025-0304", "docket", 2025, 3, 14104, 0, 0, 0, 0, "[]" + ) + return [classified, pending] + + +def _guideline_rows() -> list[GuidelineFactRow]: + rows = [] + for code, mdm, typical in ( + ("99341", "straightforward", "20"), + ("99350", "high", "60"), + ): + rows += [ + GuidelineFactRow( + FAMILY, + code, + 2022, + "selection_basis", + "history_exam_mdm", + "T6H4ZPEQ", + "p. 39", + "cpt-book", + ), + GuidelineFactRow( + FAMILY, code, 2022, "mdm_level", mdm, "T6H4ZPEQ", "p. 39", "cpt-book" + ), + GuidelineFactRow( + FAMILY, + code, + 2022, + "typical_time_min", + typical, + "T6H4ZPEQ", + "p. 39", + "cpt-book", + ), + GuidelineFactRow( + FAMILY, + code, + 2024, + "selection_basis", + "mdm_or_time", + "GQGTPGYV", + "p. 29", + "cpt-book", + ), + GuidelineFactRow( + FAMILY, code, 2024, "mdm_level", mdm, "GQGTPGYV", "p. 29", "cpt-book" + ), + ] + rows.append( + GuidelineFactRow( + FAMILY, + "99341", + 2024, + "time_threshold_min", + "15", + "GQGTPGYV", + "p. 29", + "cpt-book", + ) + ) + rows += [ + GuidelineFactRow( + FAMILY, + code, + 2023, + "deleted_in_edition", + "2022", + "3ANRT854", + "p. 48", + "cpt-book", + ) + for code in ("99324", "99343") + ] + # paraphrases written for this fixture (never book text) + rows.append( + GuidelineFactRow( + FAMILY, + "99341-99350", + 2024, + "scope_point", + "Fixture paraphrase: these visits are reported where the patient lives.", + "GQGTPGYV", + "p. 28", + "model:fake-14b@guideline-v2", + ) + ) + rows.append( + GuidelineFactRow( + FAMILY, + "99324-99350", + 2023, + "panel_action", + "Fixture paraphrase: the Panel merged the domiciliary codes into the " + "home visit codes.", + "F7SRZJD2", + "tab 10, PDF p. 4", + "cpt-panel", + ) + ) + return rows + + +def _psps_rows() -> list[PspsRow]: + """Synthetic national totals per (year, code, specialty) for the money + stakes; ``lower`` rows carry a suppressed line (a lower bound).""" + out = [] + for year in (2021, 2022, 2025, 2026): + for code, fp, im, np_ in ( + ("99341", 1000.0, 500.0, 40.0), + ("99350", 3000.0, 2500.0, 60.0), + ): + out += [ + PspsRow( + year, + code, + "08", + "Family Practice", + fp, + None, + None, + "psps", + "PSPSKEY1", + fp, + 0, + ), + PspsRow( + year, + code, + "11", + "Internal Medicine", + im, + None, + None, + "psps", + "PSPSKEY1", + im, + 0, + ), + PspsRow( + year, + code, + "50", + "Nurse Practitioner", + None, + None, + None, + "psps", + "PSPSKEY1", + np_, + 2, + ), + ] + return out + + +def _impact_rows() -> list[ImpactRow]: + return [ + ImpactRow( + 2023, + "final", + "Family Practice", + "TOTAL", + 6000.0, + 0.0, + 0.01, + 0.0, + 0.01, + "fr", + "PETM225D", + 70500, + ), + ImpactRow( + 2023, + "final", + "Internal Medicine", + "TOTAL", + 10000.0, + 0.0, + 0.0, + 0.0, + -0.005, + "fr", + "PETM225D", + 70500, + ), + ImpactRow( + 2023, + "final", + "Portable X-Ray Supplier", + "TOTAL", + 90.0, + 0.0, + -0.01, + 0.0, + -0.01, + "fr", + "PETM225D", + 70500, + ), + ] + + +def _seat_rows() -> list[SeatRow]: + url = "https://www.ama-assn.org/about/rvs-update-committee-ruc/composition-rvs-update-committee-ruc" + cpt = "https://www.ama-assn.org/about/cpt-editorial-panel/purpose-cpt-coding-system-cpt-editorial-panel" + return [ + SeatRow( + "RUC", + 2022, + "American Academy of Family Physicians", + "FAMILY PRACTICE", + "permanent", + url, + "ROSTER22", + "20220124185004", + "organization", + 1, + ), + SeatRow( + "RUC", + 2022, + "American College of Physicians", + "INTERNAL MEDICINE", + "permanent", + url, + "ROSTER22", + "20220124185004", + "organization", + 1, + ), + SeatRow( + "RUC", + 2022, + "Primary Care Rotating Seat", + "", + "rotating", + url, + "ROSTER22", + "20220124185004", + "organization", + 1, + ), + SeatRow( + "RUC", + 2023, + "American Academy of Family Physicians", + "FAMILY PRACTICE", + "permanent", + url, + "ROSTER23", + "20230323114408", + "organization", + 1, + ), + SeatRow( + "CPT_PANEL", + 2026, + "national medical specialty societies", + "", + "other", + cpt, + "ROSTERC26", + "20260129091331", + "category", + 12, + ), + ] + + +def _seat_log(con: Any) -> None: + from cms.ingest_log import ensure_table, log_ingest + + ensure_table(con) + url = "https://www.ama-assn.org/about/rvs-update-committee-ruc/composition-rvs-update-committee-ruc" + for y in (2018, 2019, 2019): # a duplicate gap row is read once + log_ingest( + con, + module="pfs.seats", + table_name="pfs.governance_seat", + rows=0, + source_file=f"{url}#{y} (no archive capture)", + rule_id="gap", + ) + log_ingest( + con, + module="pfs.seats", + table_name="pfs.governance_seat", + rows=31, + source_file=f"{url}#2024 note: parsed 31 seats, the page says 32 members", + rule_id="note", + ) + + +# ── the run ───────────────────────────────────────────────────────── + +#: the canned origin reply: CY2011 final ¶2821 states the statute (¶2818) +ORIGIN_REPLIES = { + "99341 through 99350 for new and established patient home E/M visits": { + "origins": [ + { + "kind": "statute", + "reference": "section 1833(x)(2)(B) of the Act", + "year": None, + "codes": [ + "99341", + "99342", + "99344", + "99345", + "99347", + "99348", + "99349", + "99350", + ], + "summary": "Defines primary care services to include home E/M " + "visit codes 99341-99350.", + } + ] + } +} + + +def build_con(store: Store, tmp: Path, family: Any) -> Any: + con = duckdb.connect(":memory:") + ensure_tables(con) + load_rvu(con) + # T2 lineage: every member code and link target + for code in [*family.codes, *(ln.target for ln in family.links)]: + write_events(con, code, lineage(con, store, code)) + # T4/T5 rounds: Table 14 + FR paragraphs (regex; the model declines) + rows, _ = family_rounds( + con, store, family, ask=FakeAsk(), log=RunLog(tmp / "rounds.jsonl") + ) + write_rounds(con, family.key, rows) + # T6 guidance and origin + write_guidance( + con, family.key, build_guidance(con, store, family.codes, family=family.key) + ) + origin, _ = family_origin( + con, + store, + family, + ask=FakeAsk(ORIGIN_REPLIES), + log=RunLog(tmp / "origin.jsonl"), + books=(), + ) + write_origin(con, family.key, origin) + # T7 CMS's summaries (stance asked of a fake closed-vocabulary classifier) + write_cms_summaries( + con, + family.key, + summaries( + store, + family, + classify=lambda text, labels: "support", + model="fake-14b", + log=RunLog(tmp / "cms.jsonl"), + ), + ) + # T8/T9 commenters, positions and the roll-up + write_commenters(con, _commenter_rows(), docket=DOCKET, family=family.key) + stances = _stance_rows() + write_stances(con, family.key, DOCKET, stances) + write_reaction(con, family.key, _reaction_rows(stances)) + # T9b, T10, T11 + write_guideline_facts(con, family.key, _guideline_rows()) + for (year, code), group in _grouped(_psps_rows()).items(): + write_psps(con, year, code, group) + write_specialty_impacts(con, 2023, "final", "fr", _impact_rows()) + write_seats(con, "RUC", [r for r in _seat_rows() if r.body == "RUC"]) + write_seats(con, "CPT_PANEL", [r for r in _seat_rows() if r.body == "CPT_PANEL"]) + _seat_log(con) + return con + + +def _grouped(rows: list[PspsRow]) -> dict[tuple[int, str], list[PspsRow]]: + out: dict[tuple[int, str], list[PspsRow]] = {} + for r in rows: + out.setdefault((r.year, r.hcpcs), []).append(r) + return out + + +@contextmanager +def home(tmp_path: Path): + """The fixture as a context manager: ``(con, store, family, ask)``.""" + tmp_path.mkdir(parents=True, exist_ok=True) + family = load_curated()[FAMILY] + store = build_store(tmp_path / "storage") + con = build_con(store, tmp_path, family) + try: + yield con, store, family, FakeAsk() + finally: + con.close() + store.close() + + +@pytest.fixture +def home_fixture(tmp_path: Path): + with home(tmp_path) as parts: + yield parts diff --git a/tests/pfs/test_cite.py b/tests/pfs/test_cite.py new file mode 100644 index 0000000..703633f --- /dev/null +++ b/tests/pfs/test_cite.py @@ -0,0 +1,188 @@ +"""pfs.cite — one citation per dossier fact (dossier task 13).""" + +from __future__ import annotations + +import pytest + +from pfs.cite import ( + KINDS, + Cite, + book_cite, + comment_cite, + dataset_cite, + fr_page_cite, + fr_para_cite, + guidance_cite, + rule_label, + rvu_cite, + ssa_section_url, +) +from pfs.codetables import GuidanceRow + +PETM = "https://www.federalregister.gov/documents/2022/11/18/2022-23873/medicare-and-medicaid-programs-cy-2023-payment-policies-under-the-physician-fee-schedule-and-other" + + +def test_kinds(): + assert KINDS == ( + "fr_para", + "fr_page", + "comment", + "cms_file", + "cpt_book", + "iom", + "cfr", + "mln", + "statute", + "study", + "rvu_file", + "dataset", + ) + + +def test_rule_label_moved_verbatim(): + assert ( + rule_label("Medicare Program; CY 2015 PFS Final Rule", "2014-11-13", 1251) + == "CY2015 PFS final ¶1251" + ) + assert ( + rule_label( + "CY 2021 PFS", "2020-12-28", 1578, vol="85", page=84639, kind="final" + ) + == "CY2021 PFS final 85 FR 84639 ¶1578" + ) + + +def test_fr_para_cite(home_fixture): + _con, store, _fam, _ask = home_fixture + c = fr_para_cite(store, "PETM225D", 1672) + assert c == Cite( + kind="fr_para", + label="CY2023 PFS final 87 FR 69608 ¶1672", + url=f"{PETM}#p-1672", + item_key="PETM225D", + p_id=1672, + page=69608, + locator="87 FR 69608", + ) + + +def test_fr_para_cite_unresolved_keeps_a_locator(home_fixture): + _con, store, _fam, _ask = home_fixture + c = fr_para_cite(store, "PETM225D", 99999) # no such paragraph + assert c.url == "" + assert c.label == "CY2023 PFS final ¶99999" + assert c.locator == "PETM225D ¶99999" + c = fr_para_cite(store, "NOSUCH", 3) # no such item + assert (c.url, c.label, c.locator) == ("", "NOSUCH ¶3", "NOSUCH ¶3") + + +def test_fr_page_cite(home_fixture): + _con, store, _fam, _ask = home_fixture + c = fr_page_cite(store, "54GTKR5G", 66361, table="Table 14") + assert c.label == "CY2008 PFS final 72 FR 66361 Table 14" + assert c.url.endswith("#page-66361") + assert (c.kind, c.item_key, c.page, c.locator) == ( + "fr_page", + "54GTKR5G", + 66361, + "72 FR 66361", + ) + assert ( + fr_page_cite(store, "54GTKR5G", 66361).label == "CY2008 PFS final 72 FR 66361" + ) + bad = fr_page_cite(store, "54GTKR5G", 1) # outside the rule's pages + assert bad.url == "" and bad.locator == "72 FR 1" + none = fr_page_cite(store, "NOSUCH", 5) + assert (none.url, none.label) == ("", "NOSUCH p. 5") + + +def test_comment_cite(): + c = comment_cite("CMS-2022-0113-0001") + assert c.label == "Comment CMS-2022-0113-0001" + assert c.url == "https://www.regulations.gov/comment/CMS-2022-0113-0001" + assert c.kind == "comment" + + +def test_rvu_cite(): + assert rvu_cite(2023).label == "PFS CY2023 RVU file" + assert rvu_cite(2027, proposed=True).label == "PFS CY2027 NPRM RVU file" + assert rvu_cite(2023).url.startswith("https://www.cms.gov/") + assert rvu_cite(2023).kind == "rvu_file" + + +def test_book_cite(): + c = book_cite("3ANRT854", "CPT Changes 2023", "49") + assert (c.kind, c.label, c.item_key, c.url) == ( + "cpt_book", + "CPT Changes 2023 p. 49", + "3ANRT854", + "", + ) + assert c.locator == "CPT Changes 2023 p. 49" + assert book_cite("K", "CPT 2024", "p. 29").label == "CPT 2024 p. 29" + assert ( + book_cite("F7", "Panel summary", "tab 10, PDF p. 4").label + == "Panel summary, tab 10, PDF p. 4" + ) + + +def test_dataset_cite(): + c = dataset_cite("K1", "PSPS CY2022", "https://data.cms.gov/x") + assert c == Cite( + "dataset", "PSPS CY2022", "https://data.cms.gov/x", "K1", 0, 0, "PSPS CY2022" + ) + + +def test_guidance_cite(): + cfr = guidance_cite( + GuidanceRow( + "F", "99341", "cfr", "42 CFR 425.400(c)", "", "PETM225D", 3607, 69823 + ) + ) + assert cfr.kind == "cfr" + assert cfr.label == "42 CFR 425.400(c)" + assert ( + cfr.url == "https://www.ecfr.gov/current/title-42/section-425.400#p-425.400(c)" + ) + assert (cfr.item_key, cfr.p_id, cfr.locator) == ( + "PETM225D", + 3607, + "42 CFR 425.400(c)", + ) + iom = guidance_cite( + GuidanceRow( + "F", "99341", "iom", "100-04 ch.26", "IOMKEY", "PETM225D", 3607, 0, 4 + ) + ) + assert (iom.kind, iom.url, iom.item_key, iom.page) == ("iom", "", "IOMKEY", 4) + junk = guidance_cite(GuidanceRow("F", "x", "cfr", "not a cite", "", "", 0, 0)) + assert junk.url == "" and junk.locator == "not a cite" + + +@pytest.mark.parametrize( + "ref,url", + [ + ( + "section 1834(m) of the Act", + "https://www.ssa.gov/OP_Home/ssact/title18/1834.htm", + ), + ( + "section 1899(c) of the Act", + "https://www.ssa.gov/OP_Home/ssact/title18/1899.htm", + ), + ( + "section 1866E of the Social Security Act", + "https://www.ssa.gov/OP_Home/ssact/title18/1866E.htm", + ), + ("section 5501(a) of the Affordable Care Act", ""), + ("42 CFR 410.78", ""), + ("section 1902 of the Act", ""), + ], +) +def test_ssa_section_url(ref, url): + assert ssa_section_url(ref) == url + + +def test_cite_round_trips_through_a_dict(): + c = comment_cite("X-1") + assert Cite(**c.__dict__) == c diff --git a/tests/pfs/test_citecheck.py b/tests/pfs/test_citecheck.py new file mode 100644 index 0000000..7af0366 --- /dev/null +++ b/tests/pfs/test_citecheck.py @@ -0,0 +1,214 @@ +"""pfs.citecheck — the sentence-level citation check (dossier task 13).""" + +from __future__ import annotations + +import pytest + +from pfs.cite import Cite +from pfs.citecheck import ( + Problem, + check_prose, + grounding_problems, + number_tokens, + split_sentences, +) +from pfs.dossier import Fact + + +def fact(text, values=None, fid="F1"): + return Fact( + id=fid, + kind="round", + year=2023, + codes=(), + text=text, + values=values or {}, + cite=Cite(kind="fr_para", label="x", url="u"), + ) + + +F = { + "F1": fact( + "For CY2023, the RUC recommended a work RVU of 1.00 for 99341 and CMS " + "finalized 1.00 (accept).", + {"final": 1.0}, + ), + "F2": fact( + "For CY2023, the RUC recommended a work RVU of 1.65 for 99342 and CMS " + "finalized 1.65 (accept).", + {"final": 1.65}, + "F2", + ), + "F3": fact( + "In CY2023 the payment for 99350 was $131.17 and the total changed −16.5%.", + {}, + "F3", + ), +} + + +def test_uncited_sentence_rejected(): + assert check_prose("CMS accepted the RUC values.", F)[0].kind == "uncited" + + +def test_number_from_uncited_fact_rejected(): + [p] = check_prose("99341 was finalized at 1.65 [F1].", F) + assert p.kind == "number_mismatch" + assert "1.65" in p.detail + + +def test_equivalent_number_formats_accepted(): + assert check_prose("In CY2023 99341 was set at 1.0 work RVUs [F1].", F) == [] + + +def test_unknown_fact_rejected(): + [p] = check_prose("CMS finalized 1.00 for 99341 [F9].", F) + assert p.kind == "unknown_fact" + assert "F9" in p.detail + + +def test_abbreviations_do_not_split(): + text = ( + "The U.S. statute, e.g. section 1833, i.e. the Act, No. 5 and p. 49 " + "set 1.00 for 99341 [F1]." + ) + assert split_sentences(text) == [text] + assert len(split_sentences("A one [F1]. B two [F2].")) == 2 + + +def test_tags_after_the_period_stay_with_their_sentence(): + assert split_sentences("CMS finalized 1.00 for 99341. [F1] Next [F2].") == [ + "CMS finalized 1.00 for 99341. [F1]", + "Next [F2].", + ] + assert check_prose("CMS finalized 1.00 for 99341 in CY2023. [F1]", F) == [] + + +def test_money_and_percent_normalized(): + assert number_tokens("$131.17") == {"131.17"} + assert number_tokens("−16.5%") == number_tokens("-16.5%") == {"-16.5%"} + assert number_tokens("–16.5%") == {"-16.5%"} + assert check_prose("99350 paid 131.17 in CY2023 and moved -16.5% [F3].", F) == [] + + +def test_number_tokens_normalization(): + assert number_tokens("1.00 3.60 +2 1,234 25th 2.0") == { + "1", + "3.6", + "2", + "1234", + "25th", + } + # bracketed segments (fact tags, labels) carry no numbers + assert number_tokens("x [F12] [87 FR 69608 ¶1672] y") == set() + # a range is two codes, never a negative number + assert number_tokens("99324–99328") == {"99324", "99328"} + # CY years and docket ids + assert number_tokens("CY2023") == {"2023"} + assert number_tokens("CMS-2022-0113") == {"2022", "0113"} + # HCPCS letters codes are whole tokens; modifiers carry no number + assert number_tokens("G0318 and B1") == {"G0318"} + + +def test_values_count_as_supported_numbers(): + facts = {"F1": fact("CMS finalized the value for 99341 (accept).", {"final": 1.0})} + assert check_prose("99341 was finalized at 1.00 [F1].", facts) == [] + facts = {"F1": fact("x", {"share": "12.5%", "label": "n/a"})} + assert check_prose("It was 12.5% [F1].", facts) == [] + + +def test_several_tags_in_one_bracket(): + assert check_prose("99341 and 99342 got 1.00 and 1.65 [F1, F2].", F) == [] + + +def test_problem_carries_the_sentence(): + p = check_prose("Uncited one. Fine 99341 1.00 [F1].", F) + assert p == [Problem("Uncited one.", "uncited", "no [F#] tag")] + + +@pytest.mark.parametrize("text", ["", " "]) +def test_empty_prose_has_no_problems(text): + assert check_prose(text, F) == [] + + +def test_zero_and_empty_values(): + assert number_tokens("-0.00 and +0") == {"0"} + facts = {"F1": fact("x", {"none": None, "flag": True, "n": 0})} + assert check_prose("It was 0 [F1].", facts) == [] + + +def _kind(text, kind="round", fid="F1", codes=()): + return Fact(fid, kind, 2023, codes, text, {}, Cite("fr_para", "x", "u")) + + +G = { + "F1": _kind( + "For CY2008, the RUC recommended a work RVU of 2.27 for 99326 and CMS finalized 2.63 (refine).", + codes=("99326",), + ), + "F2": _kind( + "For CY2008, CMS finalized a work RVU of 3.28 for 99350.", + fid="F2", + codes=("99350",), + ), + "F3": _kind( + "CMS reported that commenters supported the proposal (CY2005 final rule).", + "cms_summary", + "F3", + ), + "F4": _kind( + "Of 3 CY2023 commenters we classified on the work RVU valuation, 1 supported.", + "stance_split", + "F4", + ), +} + + +def test_grounded_restatement_passes(): + assert ( + grounding_problems( + "For CY2008, CMS finalized work RVUs for 99326 and 99350 [F1][F2].", G + ) + == [] + ) + assert grounding_problems("No tag here.", G) == [] # left to check_prose + + +def test_invented_words_are_ungrounded(): + [p] = grounding_problems( + "The CPT 2019 codebook introduced new codes for office visits [F1].", G + ) + assert p.kind == "ungrounded" and "introduc" in p.detail + + +def test_a_range_spanning_uncited_codes_is_rejected(): + [p] = grounding_problems( + "CMS finalized work RVUs for 99326 through 99350 [F1][F2].", G + ) + assert p.kind == "code_mismatch" and "99341" in p.detail + + +def test_cms_summary_stays_attributed_and_apart(): + [p] = grounding_problems( + "Commenters supported the proposal (CY2005 final rule) [F3].", G + ) + assert p.kind == "unattributed" + assert ( + grounding_problems( + "CMS reported that commenters supported the proposal [F3].", G + ) + == [] + ) + [m] = grounding_problems( + "CMS reported that commenters supported; we classified 3 [F3][F4].", G + ) + assert m.kind == "merged" + [u] = grounding_problems( + "Of 3 CY2023 commenters, 1 supported the work RVU valuation [F4].", G + ) + assert u.kind == "unattributed" and "classified" in u.detail + + +def test_a_range_the_fact_writes_may_be_restated(): + facts = {"F1": _kind("The Panel deleted codes 99324-99328.", "formation")} + assert grounding_problems("The Panel deleted codes 99324-99328 [F1].", facts) == [] diff --git a/tests/pfs/test_dossier.py b/tests/pfs/test_dossier.py new file mode 100644 index 0000000..3b6109b --- /dev/null +++ b/tests/pfs/test_dossier.py @@ -0,0 +1,1864 @@ +"""pfs.dossier — the cited, checked dossier of one code family (task 13).""" + +from __future__ import annotations + +import dataclasses +import json +import re + +import duckdb +import pytest + +from pfs import dossier as dos +from pfs.cite import Cite +from pfs.citecheck import check_prose +from pfs.codetables import ( + EventRow, + GuidelineFactRow, + ImpactRow, + OriginRow, + RoundRow, + SeatRow, + ensure_tables, + write_events, + write_guideline_facts, + write_origin, + write_rounds, + write_seats, + write_specialty_impacts, +) +from pfs.dossier import ( + Dossier, + Excerpt, + Fact, + TimelineEvent, + build_dossier, + cms_summary_text, + collect_facts, + coverage, + dossier_families, + event_fact_text, + governance_excerpts, + link_text, + read_dossier, + round_text, + stance_split_text, + template_event_line, + template_summary, + timeline, + write_dossier, + write_prose, +) +from pfs.runlog import RunLog +from tests.pfs.home_visits_fixture import FakeAsk + + +def _by_kind(facts): + out = {} + for f in facts: + out.setdefault(f.kind, []).append(f) + return out + + +def _texts(facts, kind): + return [f.text for f in facts if f.kind == kind] + + +# ── fixed template copy ────────────────────────────────────────────── + + +def test_round_template_copy(): + assert ( + round_text(2023, "99341", ruc=1.0, final=1.0, decision="accept") + == "For CY2023, the RUC recommended a work RVU of 1.00 for 99341 and CMS " + "finalized 1.00 (accept)." + ) + assert ( + round_text(2023, "99341", proposed=1.0) + == "For CY2023, CMS proposed a work RVU of 1.00 for 99341." + ) + assert ( + round_text(2008, "99326", ruc=2.27, final=2.63, decision="") + == "For CY2008, the RUC recommended a work RVU of 2.27 for 99326 and CMS " + "finalized 2.63." + ) + assert ( + round_text(2008, "99326", final=2.63) + == "For CY2008, CMS finalized a work RVU of 2.63 for 99326." + ) + assert ( + round_text(2008, "99326", ruc=2.27) + == "For CY2008, the RUC recommended a work RVU of 2.27 for 99326." + ) + assert round_text(2008, "99326") == "" + + +@pytest.mark.parametrize( + "q,stance,want", + [ + ( + "majority", + "support", + "CMS reported that a majority of commenters supported the proposal (CY2023 final rule).", + ), + ( + "many", + "modify", + "CMS reported that many commenters asked for changes (CY2023 final rule).", + ), + ( + "several", + "oppose", + "CMS reported that several commenters opposed the proposal (CY2023 final rule).", + ), + ( + "some", + "mixed", + "CMS reported that some commenters were divided (CY2023 final rule).", + ), + ( + "few", + "unclear", + "CMS reported that a few commenters commented (CY2023 final rule).", + ), + ( + "all", + "support", + "CMS reported that all commenters supported the proposal (CY2023 final rule).", + ), + ( + "unspecified", + "support", + "CMS reported that commenters supported the proposal (CY2023 final rule).", + ), + ( + "one", + "support", + "CMS reported that one commenter supported the proposal (CY2023 final rule).", + ), + ( + "one", + "mixed", + "CMS reported that one commenter gave a mixed view (CY2023 final rule).", + ), + ], +) +def test_cms_summary_template(q, stance, want): + assert cms_summary_text(q, stance, 2023, "final") == want + + +def test_stance_split_template(): + assert ( + stance_split_text(12, 2023, "the work RVU valuation", 6, 2, 3, 1) + == "Of 12 CY2023 commenters we classified on the work RVU valuation, 6 " + "supported, 2 asked for modifications, 3 opposed and 1 were unclear." + ) + + +@pytest.mark.parametrize( + "kind,want", + [ + ("deleted", "99343 was deleted for CY2023."), + ("cpt_panel", "99343 was acted on by the CPT Editorial Panel for CY2023."), + ("disappeared", "99343 no longer appears in the PFS RVU file from CY2023."), + ("misvalued", "99343 was named as potentially misvalued for CY2023."), + ("created", "99343 was created for CY2023."), + ( + "telehealth_list", + "99343 is named in a telehealth-list paragraph of the CY2023 rule.", + ), + ("appeared", "99343 first appears in the PFS RVU file in CY2023."), + ( + "descriptor_change", + "99343's short descriptor in the PFS RVU file changed for CY2023.", + ), + ("bundled", "99343 was bundled for CY2023."), + ], +) +def test_event_templates(kind, want): + assert event_fact_text(kind, "99343", 2023) == want + + +def test_directional_and_noted_event_templates(): + assert ( + event_fact_text("replaced_by", "G2211", 2027, to=("99212", "99215")) + == "G2211 was replaced by 99212 and 99215 for CY2027." + ) + assert event_fact_text("replaces", "99341", 2023, from_=("99343",)) == ( + "99341 replaced 99343 for CY2023." + ) + assert event_fact_text("crosswalk", "G2211", 2026, to=("90785",)) == ( + "G2211 was crosswalked to 90785 for CY2026." + ) + assert event_fact_text("revalued", "99344", 2023, note="-18.3%") == ( + "99344's non-facility total RVUs changed by -18.3% in the CY2023 RVU file." + ) + assert event_fact_text("status_change", "G2211", 2024, note="B→A") == ( + "G2211's payment status changed (B→A) in the CY2024 RVU file." + ) + assert event_fact_text("telehealth_list", "99341", 2027).startswith( + "99341 is named in a telehealth-list paragraph" + ) + + +def test_link_template(): + assert ( + link_text(2026, "G2211", "add-on") + == "From CY2026, G2211 can be reported with this family (add-on)." + ) + + +# ── facts over the fixture ─────────────────────────────────────────── + + +def test_every_fact_has_cite_url_or_locator(home_fixture): + con, store, family, _ask = home_fixture + facts = collect_facts(con, store, family) + assert len(facts) > 60 + assert [f.id for f in facts] == [f"F{i}" for i in range(1, len(facts) + 1)] + for f in facts: + assert f.cite.url or f.cite.locator, f + assert f.kind in dos.FACT_KINDS + # ids follow (year, kind order, code) + keys = [dos._order_key(f) for f in facts] + assert keys == sorted(keys) + + +def test_facts_by_kind(home_fixture): + con, store, family, _ask = home_fixture + by = _by_kind(collect_facts(con, store, family)) + assert { + "origin", + "formation", + "event", + "round", + "cms_summary", + "stance_split", + "link", + "payment", + "impact", + "money", + "seat", + } <= set(by) + rounds = _texts(by["round"], "round") + # golden values from the FR text: Table 14 (CY2008) and ¶1676/¶1685 (CY2023) + assert ( + "For CY2008, the RUC recommended a work RVU of 2.27 for 99326 and CMS " + "finalized 2.63 (refine)." in rounds + ) + assert ( + "For CY2023, the RUC recommended a work RVU of 1.00 for 99341 and CMS " + "finalized 1.00 (accept)." in rounds + ) + assert "For CY2023, CMS proposed a work RVU of 3.60 for 99350." in rounds + assert ( + "For CY2023, the RUC recommended the survey median value for 99350." in rounds + ) + assert ( + "For CY2023, the RUC recommended the survey 25th percentile value for 99341." + in rounds + ) + assert "For CY2008, commenters requested a work RVU of 2.85 for 99326." in rounds + events = _texts(by["event"], "event") + assert "99343 was deleted for CY2023." in events + assert "99343 no longer appears in the PFS RVU file from CY2023." in events + # identical facts deduped: one per code and kind + assert events.count("99343 was deleted for CY2023.") == 1 + + +def test_final_value_cites_the_finalizing_paragraph(home_fixture): + con, store, family, _ask = home_fixture + facts = collect_facts(con, store, family) + f = next( + f + for f in facts + if f.kind == "round" + and f.text.startswith( + "For CY2023, the RUC recommended a work RVU of 1.00 for 99341" + ) + ) + assert (f.cite.item_key, f.cite.p_id) == ("PETM225D", 1685) + assert ("PETM225D", 1676) in {(c.item_key, c.p_id) for c in f.also} + t14 = next( + f + for f in facts + if f.text.startswith( + "For CY2008, the RUC recommended a work RVU of 2.27 for 99326" + ) + ) + assert t14.cite.kind == "fr_page" + assert t14.cite.label == "CY2008 PFS final 72 FR 66361 Table 14" + deleted = next(f for f in facts if f.text == "99343 was deleted for CY2023.") + assert (deleted.cite.item_key, deleted.cite.p_id) == ("PETM225D", 1672) + + +def test_proposed_rule_events_never_state_a_change(home_fixture): + con, store, family, _ask = home_fixture + facts = collect_facts(con, store, family) + # G2211's CY2027 "replaced_by" event rests on the proposed rule (5ITGVDJV) + assert not [f for f in facts if f.kind == "event" and "G2211" in f.codes] + assert not [f for f in facts if f.cite.item_key == "MZ24MX5S" and f.kind == "event"] + + +def test_link_facts_cite_the_finalization(home_fixture): + con, store, family, _ask = home_fixture + links = [f for f in collect_facts(con, store, family) if f.kind == "link"] + g = next(f for f in links if f.text.startswith("From CY2023, G0318")) + assert ( + g.text + == "From CY2023, G0318 can be reported with this family (prolonged-add-on)." + ) + assert (g.cite.item_key, g.cite.p_id) == ("PETM225D", 1694) + alias = next(f for f in links if "GXXX3" in f.text) + assert ( + alias.text + == "In the CY2023 proposed rule, G0318 was the placeholder code GXXX3." + ) + assert (alias.cite.item_key, alias.cite.p_id) == ("MZ24MX5S", 880) + + +def test_link_target_events_before_since_excluded(home_fixture): + con, store, family, _ask = home_fixture + write_events( + con, + "G0318", + [ + # R92: an ESRD-era G0318 in CY2007, before the link's since (2023) + EventRow( + "G0318", + 2007, + "crosswalk", + "", + "99341", + "PETM225D", + 1694, + 69610, + "fr", + True, + "", + ), + # ¶1694: "we are finalizing our proposal to create new code G0318" + EventRow( + "G0318", + 2023, + "created", + "", + "", + "PETM225D", + 1694, + 69610, + "fr", + True, + "", + ), + # ¶1694 says nothing about the telehealth list + EventRow( + "G0318", + 2023, + "telehealth_list", + "", + "", + "PETM225D", + 1694, + 69610, + "fr", + True, + "", + ), + ], + ) + events = [ + f + for f in collect_facts(con, store, family) + if f.kind == "event" and f.codes == ("G0318",) + ] + assert [f.text for f in events] == ["G0318 was created for CY2023."] + assert events[0].values["event_kind"] == "created" + + +def _add_paragraph(store, p_id, text): + """A test-only paragraph in the CY2023 final rule (invented wording).""" + store._con().execute( + "INSERT INTO fr_anchors (item_key, p_id, page, ordinal, text) " + "VALUES ('PETM225D', ?, 69700, 1, ?)", + (p_id, text), + ) + store._con().commit() + + +def test_event_wording_checks(home_fixture): + con, store, family, _ask = home_fixture + _add_paragraph( + store, 99001, "We are adding 99341 to the Medicare Telehealth Services List." + ) + _add_paragraph(store, 99002, "We replaced code 99342 with a new code.") + _add_paragraph(store, 99003, "Code 99344 was replaced by 99345 for this year.") + _add_paragraph(store, 99004, "We crosswalked 99347 to 84571 for this year.") + write_events( + con, + "99347", + # 84571 is an FR page number, not a code: a crosswalk to nothing + [ + EventRow( + "99347", + 2023, + "crosswalk", + "", + "84571", + "PETM225D", + 99004, + 69700, + "fr", + True, + "", + ) + ], + ) + write_events( + con, + "99341", + [ + EventRow( + "99341", + 2023, + "telehealth_list", + "", + "", + "PETM225D", + 99001, + 69700, + "fr", + True, + "", + ) + ], + ) + write_events( + con, + "99342", + [ + EventRow( + "99342", + 2023, + "replaced_by", + "", + "99345", + "PETM225D", + 99002, + 69700, + "fr", + True, + "", + ) + ], + ) + write_events( + con, + "99344", + [ + EventRow( + "99344", + 2023, + "replaced_by", + "", + "99345", + "PETM225D", + 99003, + 69700, + "fr", + True, + "", + ) + ], + ) + texts = _texts(collect_facts(con, store, family), "event") + assert "99341 is named in a telehealth-list paragraph of the CY2023 rule." in texts + # the sentence names no replacement code: nothing stated + assert not [t for t in texts if t.startswith("99342 was replaced")] + assert "99344 was replaced by 99345 for CY2023." in texts + assert not [t for t in texts if "crosswalked" in t] + + +def test_comment_paragraph_events_are_dropped(home_fixture): + con, store, family, _ask = home_fixture + write_events( + con, + "99341", + [ + EventRow( + "99341", + 2023, + "created", + "", + "", + "PETM225D", + 1681, + 69609, + "fr", + True, + "", + ) + ], + ) + assert "99341 was created for CY2023." not in _texts( + collect_facts(con, store, family), "event" + ) + + +def test_cfr_typo_dropped(home_fixture): + con, store, family, _ask = home_fixture + write_origin( + con, + family.key, + [ + OriginRow( + family.key, + "99341", + "regulation", + "42 CFR 25.400(c)(1)(vi)", + None, + "CMS guidance for 99341 points to 42 CFR 25.400(c)(1)(vi).", + "cfr", + "PETM225D", + 3607, + "", + "42 CFR 25.400(c)(1)(vi)", + "guidance", + ), + OriginRow( + family.key, + "99341", + "regulation", + "42 CFR 425.400", + None, + "CMS guidance for 99341 points to 42 CFR 425.400.", + "cfr", + "PETM225D", + 3607, + "", + "42 CFR 425.400", + "guidance", + ), + ], + ) + texts = _texts(collect_facts(con, store, family), "origin") + assert not [t for t in texts if "25.400(c)(1)(vi)" in t] + assert "CMS guidance for 99341 points to 42 CFR 425.400." in texts + + +def test_origin_rows_consolidate_codes(home_fixture): + con, store, family, _ask = home_fixture + facts = collect_facts(con, store, family) + statute = [ + f for f in facts if f.kind == "origin" and "primary care services" in f.text + ] + assert len(statute) == 1 + assert statute[0].codes == ( + "99341", + "99342", + "99344", + "99345", + "99347", + "99348", + "99349", + "99350", + ) + assert ( + statute[0].also and statute[0].also[0].p_id == 2818 + ) # the reference paragraph + panel = [ + f + for f in facts + if f.kind == "formation" + and f.text.startswith("The CPT Editorial Panel deleted 99324") + ] + assert panel[0].text == ( + "The CPT Editorial Panel deleted 99324–99328, 99334–99337 and 99343, " + "effective CY2023." + ) + guidance = next(f for f in facts if "100-04 ch.26" in f.text) + assert guidance.cite.kind == "iom" and guidance.cite.locator == "100-04 ch.26" + cfr = next(f for f in facts if "42 CFR 425.400" in f.text) + assert cfr.cite.url.startswith("https://www.ecfr.gov/") + + +def test_guideline_facts(home_fixture): + con, store, family, _ask = home_fixture + facts = collect_facts(con, store, family) + texts = [f.text for f in facts] + assert ( + "In the CPT 2022 codebook, 99341 is selected on history, examination and " + "medical decision making, with straightforward medical decision making and a " + "typical time of 20 minutes." in texts + ) + change = next( + f for f in facts if f.text.startswith("In the CPT 2024 codebook, 99341") + ) + assert change.kind == "event" + assert "medical decision making or total time" in change.text + assert "a time threshold of 15 minutes" in change.text + assert change.cite.label == "CPT 2024 p. 29" + deleted = next(f for f in facts if f.text.startswith("CPT deleted")) + assert deleted.text == ( + "CPT deleted 99324 and 99343 in its 2023 code set (last listed in the " + "2022 edition)." + ) + assert deleted.cite.label == "CPT 2023 p. 48" + scope = next( + f for f in facts if f.text.startswith("Fixture paraphrase: these visits") + ) + assert scope.note == "model paraphrase, unreviewed" + panel = next(f for f in facts if "merged the domiciliary codes" in f.text) + assert panel.note == "model paraphrase, unreviewed" + assert panel.cite.label.endswith("tab 10, PDF p. 4") + + +def test_cms_summary_and_stance_split_are_separate_facts(home_fixture): + con, store, family, _ask = home_fixture + facts = collect_facts(con, store, family) + cms = [f for f in facts if f.kind == "cms_summary"] + ours = [f for f in facts if f.kind == "stance_split"] + assert ( + "CMS reported that a majority of commenters supported the proposal (CY2023 final rule)." + in [f.text for f in cms] + ) + majority = next(f for f in cms if "majority" in f.text) + assert (majority.cite.item_key, majority.cite.p_id) == ("PETM225D", 1679) + val = next(f for f in ours if "work RVU valuation" in f.text) + assert val.text.startswith( + "Of 3 CY2023 commenters we classified on the work RVU valuation, 1 supported, " + "1 asked for modifications, 1 opposed and 0 were unclear." + ) + # CMS's characterization and our counts never share a fact or a cite + assert not {f.id for f in cms} & {f.id for f in ours} + assert all(f.cite.kind == "fr_para" for f in cms) + assert all(f.cite.kind == "dataset" for f in ours) + assert all("CMS reported" not in f.text for f in ours) + assert all("we classified" not in f.text for f in cms) + + +def test_stance_accuracy_beside_every_count(home_fixture): + con, store, family, _ask = home_fixture + ours = [f for f in collect_facts(con, store, family) if f.kind == "stance_split"] + assert len(ours) == 5 # four events and the docket + for f in ours: + assert "held-out set the prompt was never tuned on" in f.text + assert "79%" in f.text and "74%" in f.text + assert "CMS-2025-0304" in f.text and "CMS-2026-2377" in f.text + assert f.values["recall"] == 0.792 + docket = next(f for f in ours if "docket" in f.text.split(".")[0]) + assert docket.text.startswith( + "Of 6 CY2023 commenters on this family in docket CMS-2022-0113, we " + "classified 4 with a firm position: 2 supported, 1 asked for modifications " + "and 1 opposed; 1 more was unclear." + ) + # the unclassified docket is "not classified", never 0/0 + assert not [f for f in ours if "CMS-2025-0304," in f.text.split("(")[0]] + + +def test_stance_accuracy_line_variants(): + tuned = dos.stance_accuracy_line( + { + "recall": 0.5, + "direction": 0.75, + "n_items": 20, + "n_positions": 27, + "docket": "CMS-2022-0113", + "in_sample": True, + } + ) + assert "on the tuning set" in tuned and "CMS-2022-0113" in tuned + assert ( + dos.stance_accuracy_line(None) + == "Preliminary model classification; its accuracy is not yet measured." + ) + + +def test_money_facts(home_fixture): + con, store, family, _ask = home_fixture + money = [f for f in collect_facts(con, store, family) if f.kind == "money"] + texts = [f.text for f in money] + assert ( + "For CY2023, the family gained new payment through G0318 (new, amount n/a)." + in texts + ) + np_ = [t for t in texts if t.startswith("For CY2023, NURSE PRACTITIONER")] + assert np_ and "at least 100 of the family's services" in np_[0] + assert "(CMS suppresses lines under 11 services)" in np_[0] + assert not [t for t in texts if "$-" in t or "at least $-" in t] + assert all("new, amount n/a" not in t for t in texts if "billed" in t) + + +def test_lower_bound_cut_wording(): + assert dos.money_change(-1234.4, lower_bound=True) == "a cut of at least $1,234" + assert ( + dos.money_change(1234.4, lower_bound=True) == "an increase of at least $1,234" + ) + assert dos.money_change(-5.0, lower_bound=False) == "a cut of $5" + assert dos.money_change(0.0, lower_bound=False) == "no change" + assert dos.money_change(None, lower_bound=False) == "" + + +def test_seat_facts_use_the_prior_year_roster(home_fixture): + con, store, family, _ask = home_fixture + seats = [f.text for f in collect_facts(con, store, family) if f.kind == "seat"] + assert ( + "On the 2022 RUC roster (the RUC that valued CY2023 met in 2022), FAMILY " + "PRACTICE held 1 permanent and 0 rotating seats." in seats + ) + assert ( + "On the 2022 RUC roster, the Primary Care Rotating Seat is a rotating seat." + in seats + ) + assert any( + t.startswith( + "The 2026 CPT Editorial Panel roster lists 12 seats for national medical specialty societies" + ) + for t in seats + ) + + +def test_roster_year_falls_back_to_the_rule_year(): + assert dos.roster_year({2023}, 2023) == ( + 2023, + " (the roster of CY2023 itself; the 2022 roster is not captured)", + ) + assert dos.roster_year({2022, 2023}, 2023) == ( + 2022, + " (the RUC that valued CY2023 met in 2022)", + ) + assert dos.roster_year(set(), 2023) == (None, "") + + +def test_impact_facts(home_fixture): + con, store, family, _ask = home_fixture + impact = [f.text for f in collect_facts(con, store, family) if f.kind == "impact"] + assert ( + "CMS estimated the CY2023 final rule's combined impact on allowed charges " + "for Family Practice at 1%." in impact + ) + assert not [t for t in impact if "Portable X-Ray" in t] + + +def test_payment_facts_and_rows(home_fixture): + con, store, family, _ask = home_fixture + d = build_dossier(con, store, family) + pay = [f for f in d.facts.values() if f.kind == "payment"] + assert pay and all(f.cite.kind == "rvu_file" for f in pay) + assert any( + f.text.startswith("For CY2027, CMS proposed a national non-facility payment") + for f in pay + ) + assert all("description" not in row for row in d.payment) + years_99343 = sorted({r["year"] for r in d.payment if r["code"] == "99343"}) + assert years_99343[-1] == 2022 + + +def test_coverage_notes_from_data(home_fixture): + con, store, family, _ask = home_fixture + notes = coverage(con, store, family) + assert "Federal Register PFS rules before CY2002 not yet captured." in notes + assert "RVU files before 2015 not yet loaded." in notes + assert "Public comment dockets before the CY2023 rule not yet captured." in notes + assert "Governance literature not yet ingested." in notes + assert ( + "Specialty impact rows not matched to a specialty: Portable X-Ray Supplier." + in notes + ) + assert ( + "RUC rosters captured 2022–2023 (2018–2019 not captured); " + "CPT Panel rosters captured 2026." in notes + ) + assert "RUC roster notes: 2024: parsed 31 seats, the page says 32 members." in notes + assert ( + "Comment stance classified for 1 of 2 dockets with family commenters (CMS-2022-0113)." + in notes + ) + assert not [n for n in notes if n.startswith("No conversion factor")] + + +def test_coverage_lines_without_data(): + con = duckdb.connect(":memory:") + try: + ensure_tables(con) + con.execute("CREATE TABLE pfs.rvu (hcpcs VARCHAR, mod VARCHAR, year INTEGER)") + con.execute("INSERT INTO pfs.rvu VALUES ('99341', NULL, 1990)") + from pfs.curated import load_curated + + fam = load_curated()["HOME-VISITS"] + + from bib.store import Store + + store = Store(":memory:") + try: + notes = coverage(con, store, fam) + finally: + store.close() + assert "Federal Register PFS rules not yet captured." in notes + assert "RUC/CPT Panel seat data not captured." in notes + assert "No conversion factor on file for 1990; payment not computed." in notes + assert "RVU files before 1990 not yet loaded." in notes + finally: + con.close() + + +def test_commenter_names_come_from_own_record(home_fixture): + con, store, family, _ask = home_fixture + d = build_dossier(con, store, family) + blob = d.to_json() + # the bib title says "Jane Doe: CMS-2022-0113-0001"; the comment's own + # regulations.gov record (pfs.commenter.submitter_name) says Mary Major + assert "Doe" not in blob and "Roe" not in blob and "Poe" not in blob + names = { + name + for panel in d.stakeholders + for unit in panel["units"] + for name in unit["names"] + } + own = { + r[0] or r[1] or "individual commenter" + for r in con.execute( + "SELECT CASE WHEN org_type IN ('individual','individual_clinician') " + "THEN submitter_name ELSE org_name END, org_name FROM pfs.commenter" + ).fetchall() + } + assert "Mary Major" in names + assert "American Academy of Home Care Medicine" in names + assert names <= own + + +def test_stakeholders_pair_new_payment_with_the_link_event(home_fixture): + con, store, family, _ask = home_fixture + d = build_dossier(con, store, family) + by_event = {p["event_key"]: p for p in d.stakeholders} + g = by_event["HOME-VISITS:2023:G0318"] + val = by_event["HOME-VISITS:2023:valuation"] + fp_g = next( + u + for u in g["units"] + if u["specialty"] == "FAMILY PRACTICE" and u["org_type"] == "specialty_society" + ) + fp_v = next( + u + for u in val["units"] + if u["specialty"] == "FAMILY PRACTICE" and u["org_type"] == "specialty_society" + ) + assert ( + fp_g["expected"] == "support" + and "new payment (G0318)" in fp_g["expected_reason"] + ) + assert "new payment" not in fp_v["expected_reason"] + assert val["accuracy"].startswith("Preliminary model classification") + assert val["roster_year"] == 2022 + assert val["seats"]["FAMILY PRACTICE"]["ruc_permanent"] == 1 + lines = dos.stakeholder_lines(d) + assert any("Mary Major" in line for line in lines) + + +def test_timeline(home_fixture): + con, store, family, _ask = home_fixture + facts = collect_facts(con, store, family) + events = timeline(facts) + assert all(isinstance(e, TimelineEvent) for e in events) + years = [e.year for e in events] + assert years == sorted(years) + assert {2008, 2023, 2026, 2027} <= set(years) + by = {(e.year, e.kind): e for e in events} + val23 = by[(2023, "valuation")] + assert val23.stance_fact_ids and val23.cms_summary_fact_ids + ids = {f.id: f for f in facts} + assert all(ids[i].kind == "stance_split" for i in val23.stance_fact_ids) + assert all(ids[i].kind == "cms_summary" for i in val23.cms_summary_fact_ids) + g = by[(2023, "link:G0318")] + assert any("G0318" in ids[i].text for i in g.stance_fact_ids) + deleted = by[(2023, "deleted")] + assert deleted.what_changed.startswith( + "99324–99328, 99334–99337, 99339, 99340 and 99343 were deleted for CY2023 [F" + ) + for e in events: + assert check_prose(e.what_changed, ids) == [], e + + +def test_template_lines_pass_the_check(home_fixture): + con, store, family, _ask = home_fixture + facts = collect_facts(con, store, family) + ids = {f.id: f for f in facts} + events = timeline(facts) + for e in events: + assert check_prose(template_event_line(e, ids), ids) == [] + assert dos.grounding_problems(template_event_line(e, ids), ids) == [] + summary = template_summary(facts, events) + assert 1 <= len(re.findall(r"\[F\d+", summary)) and check_prose(summary, ids) == [] + assert len(dos.split_sentences(summary)) <= 5 + + +def _echo(system, user): + """A well-behaved model: restates the first fact line of the prompt.""" + m = re.search(r"^\[(F\d+)\] (.+)$", user, re.M) + return {"text": f"{m.group(2).rstrip('.')} [{m.group(1)}]."} + + +def test_model_prose_accepted(home_fixture): + con, store, family, _ask = home_fixture + facts = collect_facts(con, store, family) + events = timeline(facts) + ask = FakeAsk(default=_echo) + summary, lines, extractor, ok = write_prose(facts, events, ask) + assert ok is True and extractor == "model:fake-14b" + assert len(lines) == len(events) + ids = {f.id: f for f in facts} + assert check_prose(summary, ids) == [] + assert all(check_prose(line, ids) == [] for line in lines.values()) + assert len(ask.calls) == len(events) + 1 + # unreviewed paraphrases never reach the model + assert "Fixture paraphrase" not in "".join(u for _s, u in ask.calls) + + +def test_prose_rejected_twice_falls_back_to_templates(home_fixture): + con, store, family, _ask = home_fixture + facts = collect_facts(con, store, family) + events = timeline(facts) + ask = FakeAsk(default={"text": "CMS accepted the RUC values."}) + summary, lines, extractor, ok = write_prose(facts, events, ask) + assert extractor == "template" and ok is True + assert summary == template_summary(facts, events) + ids = {f.id: f for f in facts} + assert lines == {i: template_event_line(e, ids) for i, e in enumerate(events)} + assert len(ask.calls) == 2 * (len(events) + 1) # one retry each + retry = ask.calls[1][1] + assert "uncited" in retry + + +def test_retry_with_problems_listed_can_succeed(home_fixture): + con, store, family, _ask = home_fixture + facts = collect_facts(con, store, family) + events = timeline(facts)[:1] + answers = iter([{"text": "No tag here."}, None]) + + def first_bad(system, user): + nxt = next(answers, None) + return nxt if nxt is not None or "Problems" not in user else _echo(system, user) + + ask = FakeAsk(default=first_bad) + summary, lines, extractor, ok = write_prose(facts, events, ask) + assert extractor.startswith("model:fake-14b") + assert ok + + +def test_mixed_prose_extractor(home_fixture): + con, store, family, _ask = home_fixture + facts = collect_facts(con, store, family) + events = timeline(facts)[:2] + + def only_summary(system, user): + return _echo(system, user) if "summary" in system.lower() else {"text": "x"} + + summary, lines, extractor, ok = write_prose( + facts, events, FakeAsk(default=only_summary) + ) + assert extractor == "model:fake-14b+template" + + +def test_no_model_means_templates(home_fixture): + con, store, family, _ask = home_fixture + facts = collect_facts(con, store, family) + events = timeline(facts) + summary, lines, extractor, ok = write_prose(facts, events, None) + assert (extractor, ok) == ("template", True) + + +def test_prose_ledger_resumes_and_replays(home_fixture, tmp_path): + con, store, family, _ask = home_fixture + facts = collect_facts(con, store, family) + events = timeline(facts)[:3] + log = RunLog(tmp_path / "prose.jsonl") + ask = FakeAsk(default=_echo) + first = write_prose(facts, events, ask, log=log, limit=2) + assert len(ask.calls) == 2 + assert first[2] == "model:fake-14b+template" + second = write_prose(facts, events, ask, log=RunLog(tmp_path / "prose.jsonl")) + assert len(ask.calls) == 4 # the two not yet logged + replay = write_prose( + facts, + events, + None, + log=RunLog(tmp_path / "prose.jsonl"), + replay_model="fake-14b", + ) + assert replay == second + assert len(ask.calls) == 4 + + +def test_unchecked_model_text_is_never_returned(home_fixture): + con, store, family, _ask = home_fixture + facts = collect_facts(con, store, family) + events = timeline(facts)[:1] + # numbers no cited fact carries + ask = FakeAsk( + default=lambda s, u: {"text": f"99341 was paid $999.99 [{facts[0].id}]."} + ) + summary, lines, extractor, ok = write_prose(facts, events, ask) + assert "999.99" not in summary and "999.99" not in lines[0] + assert extractor == "template" + + +# ── assembly, storage, governance ──────────────────────────────────── + + +def test_build_dossier(home_fixture): + con, store, family, _ask = home_fixture + exc = Excerpt( + "A finding about the RUC.", + dos.Cite("study", "Study p. 3", "https://x", "S1", 0, 3), + ) + d = build_dossier(con, store, family, excerpts=[exc]) + assert d.family == "HOME-VISITS" and d.name == "Home or Residence Services" + assert d.check_passed is True and d.extractor == "template" + assert d.codes == family.codes + assert d.years_active == "CY2008–CY2027" + assert "8 active" in d.status and "12 deleted" in d.status + assert d.governance == [exc] + assert [f for f in d.facts.values() if f.kind == "finding"] + assert d.sources["study"][0]["label"] == "Study p. 3" + assert d.review and all( + r["reason"] == "model paraphrase, unreviewed" for r in d.review + ) + assert d.utilization == [] + assert d.rounds and all( + "url" in r["cites"]["final_work_rvu"] for r in d.rounds if "final_work_rvu" in r + ) + r = next( + r + for r in d.rounds + if r["code"] == "99341" and r["rule_year"] == 2023 and r["rule_kind"] == "final" + ) + assert ( + "comparators" not in r and "survey_intra_min" not in r + ) # never an empty field + assert r["rationale"]["url"].endswith("#p-1685") + assert d.timeline and d.summary + assert d.stance_accuracy.startswith("Preliminary model classification") + + +def test_json_roundtrip(home_fixture): + con, store, family, _ask = home_fixture + d = build_dossier(con, store, family, ask=FakeAsk(default=_echo)) + back = Dossier.from_json(d.to_json()) + assert back == d + assert isinstance(back.facts["F1"], Fact) + assert isinstance(back.timeline[0], TimelineEvent) + + +def test_write_read_dossier(home_fixture): + con, store, family, _ask = home_fixture + assert dossier_families(con) == () + d = build_dossier(con, store, family) + write_dossier(con, d) + write_dossier(con, d) # delete-then-insert + assert con.execute("SELECT count(*) FROM pfs.dossier").fetchone()[0] == 1 + assert dossier_families(con) == ("HOME-VISITS",) + assert read_dossier(con, "HOME-VISITS") == d + assert read_dossier(con, "NOPE") is None + + +def test_dossier_families_missing_table(): + con = duckdb.connect(":memory:") + try: + assert dossier_families(con) == () + assert read_dossier(con, "X") is None + finally: + con.close() + + class _Broken: + def execute(self, *a): + raise RuntimeError("disk on fire") + + with pytest.raises(RuntimeError): + dossier_families(_Broken()) + with pytest.raises(RuntimeError): + read_dossier(_Broken(), "X") + + +def test_governance_excerpts(home_fixture, monkeypatch): + _con, store, _family, _ask = home_fixture + assert ( + governance_excerpts(object(), object(), store, "Home or Residence Services") + == [] + ) + from bib.item import Source + + key = store.create( + Source(title="RUC study", url="https://example.org/ruc"), + tags=["source:governance-lit"], + ) + calls = [] + + def fake_search(q, *, cfg, pool, collection, item_keys, limit): + calls.append((q, collection, tuple(item_keys), limit)) + return [ + { + "label": f"RUC study p. 3 [{q[:4]}]", + "url": "https://example.org/ruc#3", + "item_key": key, + "page": "3", + "text": "word " * 100, + }, + { + "label": "dup", + "url": "", + "item_key": key, + "page": "", + "text": "short finding", + }, + ] + + monkeypatch.setattr("llm.search.search", fake_search) + got = governance_excerpts( + object(), object(), store, "Home or Residence Services", k=3 + ) + assert len(got) == 3 + assert calls[0] == ("Home or Residence Services valuation", "corpus", (key,), 3) + assert len(calls) == 5 + assert all(len(e.text) <= 300 for e in got) + assert got[0].cite.kind == "study" and got[0].cite.page == 3 + assert got[0].text.endswith("…") + + +def test_split_sentences_reexported(): + assert dos.split_sentences("A [F1]. B [F2].") == ["A [F1].", "B [F2]."] + + +def test_fact_dataclass_is_frozen(): + f = Fact("F1", "round", 2023, ("99341",), "t", {}, dos.Cite("fr_para", "l", "u")) + with pytest.raises(dataclasses.FrozenInstanceError): + f.text = "x" # type: ignore[misc] + assert json.loads(json.dumps(dos._fact_dict(f)))["id"] == "F1" + + +# ── edges: every branch of the assembly ────────────────────────────── + + +def _round(**kw): + base = dict( + family="HOME-VISITS", + code="99341", + rule_year=2020, + item_key="PETM225D", + rule_kind="proposed", + p_id=0, + page=0, + source="fr-para", + table_title="", + ruc_work_rvu=None, + ruc_percentile="", + survey_intra_min=None, + survey_total_min=None, + comparators="", + surveying_societies="", + requested_work_rvu=None, + proposed_work_rvu=None, + final_work_rvu=None, + decision="", + rationale_p_id=0, + rationale_quote="", + pe_note="", + extractor="regex", + final_p_id=0, + ruc_p_id=0, + field_cites="", + ) + base.update(kw) + return RoundRow(**base) + + +def test_rows_reraises_other_errors(): + def boom(*a): + raise RuntimeError("not a catalog error") + + with pytest.raises(RuntimeError): + dos._rows(boom) + + +def test_round_edges(home_fixture): + con, store, family, _ask = home_fixture + write_rounds( + con, + family.key, + [ + # a proposed-rule RUC value with no final round: its own fact + _round( + code="99342", + ruc_work_rvu=1.65, + proposed_work_rvu=1.6, + p_id=1676, + survey_total_min=97.0, + survey_intra_min=40.0, + comparators="99215", + pe_note="none of note; finalizing removal of supplies", + field_cites=json.dumps({"pe_note": [1677, 1683]}), + ), + # no paragraph anywhere: cited to the FR page (table row) + _round(code="99343", ruc_work_rvu=2.0, page=69608), + # a final row with the RUC value only + _round( + code="99344", + rule_kind="final", + ruc_work_rvu=2.87, + p_id=1676, + pe_note="x" * 300, + ), + # a correction notice yields nothing + _round(code="99345", rule_kind="correction", final_work_rvu=9.0), + # a final row with nothing to say + _round(code="99347", rule_kind="final"), + ], + ) + facts = collect_facts(con, store, family) + texts = [f.text for f in facts] + assert "For CY2020, CMS proposed a work RVU of 1.60 for 99342." in texts + assert "For CY2020, the RUC recommended a work RVU of 1.65 for 99342." in texts + assert "For CY2020, the RUC survey total time for 99342 was 97 minutes." in texts + assert ( + "For CY2020, the RUC survey intra-service time for 99342 was 40 minutes." + in texts + ) + assert "For CY2020, the comparator codes named for 99342 were 99215." in texts + assert "For CY2020, the RUC recommended a work RVU of 2.87 for 99344." in texts + assert not [t for t in texts if "9.00" in t] + page = next(f for f in facts if "2.00 for 99343" in f.text) + assert page.cite.kind == "fr_page" and page.cite.page == 69608 + pe = [f for f in facts if f.kind == "pe"] + assert {f.note for f in pe} == {dos.UNREVIEWED_EXTRACT} + pe342 = next(f for f in pe if f.codes == ("99342",)) + assert ( + pe342.text + == "CY2020 proposed rule, direct PE inputs for 99342: finalizing removal of supplies." + ) + assert (pe342.cite.p_id, pe342.also[0].p_id) == (1677, 1683) + pe344 = next(f for f in pe if f.codes == ("99344",)) + assert len(pe344.text) < 300 + + +def test_guideline_edges(home_fixture): + con, store, family, _ask = home_fixture + write_guideline_facts( + con, + family.key, + [ + GuidelineFactRow( + family.key, "99341", 2021, "addon", "true", "K", "p. 2", "cpt-book" + ), + GuidelineFactRow( + family.key, "99341", 2021, "mdm_level", "low", "K", "p. 2", "cpt-book" + ), + GuidelineFactRow( + family.key, + "99350", + 2021, + "selection_basis", + "other_basis", + "K", + "p. 2", + "cpt-book", + ), + GuidelineFactRow( + family.key, + "99341", + 2021, + "scope_point", + "A single-code point.", + "K", + "p. 2", + "m", + ), + GuidelineFactRow( + family.key, + "99342", + 2021, + "scope_point", + "A single-code point.", + "K", + "p. 2", + "m", + ), + GuidelineFactRow( + family.key, + "G9999", + 2021, + "scope_point", + "Off-family.", + "K", + "p. 2", + "m", + ), + GuidelineFactRow( + family.key, + "99341", + 2021, + "deleted_in_edition", + "n/a", + "K", + "p. 3", + "cpt-book", + ), + ], + ) + facts = collect_facts(con, store, family) + texts = [f.text for f in facts] + assert ( + "In the CPT 2021 codebook, 99341 carries with low medical decision making and add-on status." + in texts + ) + assert "In the CPT 2021 codebook, 99350 is selected on other basis." in texts + # identical paraphrases of one year collapse to one fact + assert texts.count("A single-code point.") == 1 + off = next(f for f in facts if f.text == "Off-family.") + assert off.codes == () + odd = next(f for f in facts if f.text.startswith("CPT deleted 99341")) + assert odd.text == "CPT deleted 99341 in its 2021 code set." and odd.year == 2021 + + +def test_origin_edges(home_fixture): + con, store, family, _ask = home_fixture + write_origin( + con, + family.key, + [ + OriginRow( + family.key, + "99341", + "cpt_panel", + "CPT Editorial Panel action", + 2023, + "Revised the codes.", + "cpt_book", + "3ANRT854", + 0, + "49", + "CPT Changes 2023, p. 49", + "model:x@origin-v1", + ), + OriginRow( + family.key, + "99342", + "cpt_panel", + "CPT Editorial Panel action", + 2023, + "Revised others.", + "cpt_book", + "3ANRT854", + 0, + "50", + "no page here", + "model:x@origin-v1", + ), + OriginRow( + family.key, + "99341", + "coverage", + "100-04 ch.12 §30.6.14.1", + 2019, + "The CY2019 final rule removed a requirement in 100-04 ch.12 §30.6.14.1.", + "iom", + "PETM225D", + 1685, + "69609", + "100-04 ch.12 §30.6.14.1; 87 FR 69609", + "guidance", + 1684, + ), + OriginRow( + family.key, + "99341", + "statute", + "section 1834(m) of the Act", + None, + "A statute about telehealth.", + "fr_para", + "PETM225D", + 1672, + "69608", + "87 FR 69608, ¶1672", + "model:x@origin-v1", + 1672, + ), + ], + ) + facts = collect_facts(con, store, family) + book = next(f for f in facts if f.text == "Revised the codes.") + assert book.kind == "formation" and book.cite.label == "CPT Changes 2023 p. 49" + nopage = next(f for f in facts if f.text == "Revised others.") + assert nopage.cite.label == "no page here p. 50" + removal = next( + f for f in facts if f.text.startswith("The CY2019 final rule removed") + ) + assert removal.cite.kind == "fr_para" and removal.cite.p_id == 1685 + assert removal.also[0].kind == "iom" and removal.also[0].p_id == 1684 + statute = next(f for f in facts if f.text == "A statute about telehealth.") + assert statute.also[-1] == Cite( + "statute", + "section 1834(m) of the Act", + "https://www.ssa.gov/OP_Home/ssact/title18/1834.htm", + locator="section 1834(m) of the Act", + ) + + +def test_event_edges(home_fixture): + con, store, family, _ask = home_fixture + write_events( + con, + "99341", + [ + # not a lineage kind the dossier states + EventRow( + "99341", + 2013, + "cpt_changed", + "", + "", + "GQGTPGYV", + 0, + 0, + "cpt", + True, + "CPT Changes 2013", + ), + # an RVU-file row of a kind the RVU file cannot state + EventRow("99341", 2016, "created", "", "", "", 0, 0, "rvu", False, ""), + # a deletion the paragraph does not read as one (¶1685 names no code) + EventRow( + "99341", + 2023, + "deleted", + "", + "", + "PETM225D", + 1685, + 69609, + "fr", + True, + "", + ), + # a deletion the sentence names but does not delete (a successor) + EventRow( + "99341", + 2023, + "cpt_panel", + "", + "", + "PETM225D", + 1672, + 69608, + "fr", + True, + "", + ), + # an unknown rule item + EventRow("99341", 2023, "created", "", "", "NOSUCH", 3, 1, "fr", True, ""), + # a crosswalk to page numbers only + EventRow( + "99341", + 2023, + "crosswalk", + "", + "69608", + "PETM225D", + 1672, + 69608, + "fr", + True, + "", + ), + # a status change keeps its note + EventRow( + "99341", 2024, "status_change", "", "", "", 0, 0, "rvu", True, "A→I" + ), + ], + ) + write_events( + con, + "99343", + [ + EventRow( + "99343", + 2023, + "deleted", + "", + "", + "PETM225D", + 1672, + 69608, + "fr", + True, + "", + ), + EventRow("99343", 2024, "disappeared", "", "", "", 0, 0, "rvu", True, ""), + EventRow("99343", 2023, "disappeared", "", "", "", 0, 0, "rvu", True, ""), + ], + ) + events = [f for f in collect_facts(con, store, family) if f.kind == "event"] + texts = [f.text for f in events] + assert "99341's payment status changed (A→I) in the CY2024 RVU file." in texts + assert not [t for t in texts if t.startswith("99341") and "2023" in t] + assert "99343 no longer appears in the PFS RVU file from CY2024." not in texts + assert "99343 no longer appears in the PFS RVU file from CY2023." in texts + + +def test_known_codes_without_rvu(): + con = duckdb.connect(":memory:") + try: + from pfs.curated import load_curated + + fam = load_curated()["HOME-VISITS"] + assert dos._known_codes(con, fam) >= {"99341", "G0318"} + + class _Broken: + def execute(self, *a): + raise RuntimeError("boom") + + with pytest.raises(RuntimeError): + dos._known_codes(_Broken(), fam) + finally: + con.close() + + +def test_link_edges(home_fixture): + con, store, family, _ask = home_fixture + from pfs.curated import CuratedLink + + fam = dataclasses.replace( + family, + links=( + CuratedLink("add-on", "G9001", None, None, "", 0, 0, 0), + CuratedLink("add-on", "G9002", 2024, None, "54GTKR5G", 0, 66361, 0), + CuratedLink("add-on", "G9003", 2025, None, "", 0, 0, 2025), + ), + ) + links = [f for f in collect_facts(con, store, fam) if f.kind == "link"] + assert [f.codes for f in links] == [("G9002",), ("G9003",)] + assert links[0].cite.kind == "fr_page" and links[1].cite.kind == "rvu_file" + + +def test_impact_from_the_508_file(home_fixture): + con, store, family, _ask = home_fixture + from bib.item import Source + + key = store.create( + Source(title="CY2023 impact file", url="https://cms.example/impact.xlsx") + ) + write_specialty_impacts( + con, + 2023, + "proposed", + "508", + [ + ImpactRow( + 2023, + "proposed", + "Family Practice", + "TOTAL", + 1.0, + 0, + 0, + 0, + 0.02, + "508", + key, + 0, + ), + ImpactRow( + 2023, + "proposed", + "Internal Medicine", + "TOTAL", + 1.0, + 0, + 0, + 0, + None, + "508", + "NOSUCH", + 0, + ), + ImpactRow( + 2023, + "proposed", + "Family Practice", + "Facility", + 1.0, + 0, + 0, + 0, + 0.5, + "508", + key, + 0, + ), + ImpactRow( + 2023, "proposed", "TOTAL", "TOTAL", 1.0, 0, 0, 0, 0.5, "508", key, 0 + ), + ], + ) + write_specialty_impacts( + con, + 2023, + "final", + "508", + [ + ImpactRow( + 2023, + "final", + "Family Practice", + "TOTAL", + 1.0, + 0, + 0, + 0, + 0.03, + "508", + "NOSUCH", + 0, + ) + ], + ) + impact = [f for f in collect_facts(con, store, family) if f.kind == "impact"] + p = next(f for f in impact if "proposed" in f.text) + assert p.text.endswith("for Family Practice at 2%.") + assert p.cite.kind == "dataset" and p.cite.url == "https://cms.example/impact.xlsx" + nourl = next(f for f in impact if "at 3%" in f.text) + assert nourl.cite.url == "" + + +def test_money_edges(): + from pfs.stakes import SpecialtyMoney + + assert dos._money_facts(2023, [], [], None) == [] + m = SpecialtyMoney("FAMILY PRACTICE", 1000.0, None, None, 0.5) + [f] = dos._money_facts(2023, [m], [], None) + assert "no final payment change is computed for those services" in f.text + # no PSPS row on file: the year before the rule year's dataset + assert f.cite.label == "Medicare Physician/Supplier Procedure Summary CY2022" + + +def test_specialty_vocab_reraises(): + class _Broken: + def execute(self, *a): + raise RuntimeError("boom") + + with pytest.raises(RuntimeError): + dos._specialty_vocab(_Broken(), set()) + + +def test_payment_rows_without_rvu_tables(): + con = duckdb.connect(":memory:") + try: + from pfs.curated import load_curated + + assert dos._payment_rows(con, load_curated()["HOME-VISITS"]) == [] + + class _Broken: + def execute(self, *a): + raise RuntimeError("boom") + + with pytest.raises(RuntimeError): + dos._payment_rows(_Broken(), load_curated()["HOME-VISITS"]) + finally: + con.close() + + +def test_payment_fact_for_an_unpaid_status(): + from pfs.valuation import ValuationRow + + row = ValuationRow( + "G2211", + "", + "CY2022 final", + 2022, + False, + "B", + 0.33, + 0.1, + 0.1, + 0.01, + 0.44, + 0.44, + 34.6062, + None, + None, + "[PFS CY2022 Addendum B]", + "", + "", + ) + [f] = dos._payment_facts([row]) + assert ( + f.text + == "For CY2022, G2211 carried payment status B, so no national payment is computed." + ) + assert f.also == () + + +def test_seat_log_edges(home_fixture): + con, _store, _family, _ask = home_fixture + con.execute( + "INSERT INTO cms.ingest_log (module, rule_id, source_file) VALUES " + "('pfs.seats', 'gap', 'no year here'), " + "('pfs.seats', 'note', 'https://x#2025 (a gap reason, not a note)')" + ) + gaps, notes = dos._seat_log(con) + assert gaps["RUC"] == {2018, 2019} + assert notes == ["2024: parsed 31 seats, the page says 32 members"] + + class _Broken: + def execute(self, *a): + raise RuntimeError("boom") + + with pytest.raises(RuntimeError): + dos._seat_log(_Broken()) + + +def test_seat_coverage_edges(): + con = duckdb.connect(":memory:") + try: + ensure_tables(con) + write_seats( + con, + "RUC", + [ + SeatRow( + "RUC", + 2022, + "A society", + "FAMILY PRACTICE", + "permanent", + "u", + "K", + "", + ) + ], + ) + assert dos._seat_coverage(con) == [ + "RUC rosters captured 2022; CPT Panel rosters not captured." + ] + assert dos._seat_log(con) == ({}, []) + finally: + con.close() + + +def test_coverage_without_rvu_table(home_fixture): + _con, store, family, _ask = home_fixture + con = duckdb.connect(":memory:") + try: + ensure_tables(con) + notes = coverage(con, store, family) + assert "RVU files not yet loaded." in notes + + class _Broken: + def execute(self, *a): + raise RuntimeError("boom") + + with pytest.raises(RuntimeError): + coverage(_Broken(), store, family) + finally: + con.close() + + +def _f(fid, kind, year, text, codes=(), **values): + return Fact(fid, kind, year, tuple(codes), text, values, Cite("fr_para", "l", "u")) + + +def test_timeline_comment_only_years_and_fallbacks(): + facts = [ + _f( + "F1", + "cms_summary", + 2005, + "CMS reported that one commenter commented (CY2005 final rule).", + ("99341",), + ), + _f( + "F2", + "event", + 2010, + "99341 was created for CY2010.", + ("99341",), + event_kind="created", + ), + _f( + "F3", + "cms_summary", + 2010, + "CMS reported that commenters commented (CY2010 final rule).", + ("99350",), + ), + _f( + "F4", + "stance_split", + 2011, + "Of 2 CY2011 commenters we classified on the coding changes, 1 supported, 1 asked for modifications, 0 opposed and 0 were unclear. Preliminary.", + event_key="X:2011:coding", + ), + ] + events = timeline(facts) + by = {(e.year, e.kind): e for e in events} + assert by[(2005, "comments")].cms_summary_fact_ids == ("F1",) + assert ( + by[(2005, "comments")].what_changed + == "CMS reported that one commenter commented (CY2005 final rule) [F1]." + ) + assert by[(2010, "created")].cms_summary_fact_ids == ("F3",) + assert by[(2011, "comments")].what_changed.startswith( + "Of 2 CY2011 commenters" + ) and by[(2011, "comments")].what_changed.endswith("[F4].") + ids = {f.id: f for f in facts} + assert check_prose(template_summary(facts, events), ids) == [] + + +def test_prose_too_long_is_a_problem(home_fixture): + con, store, family, _ask = home_fixture + facts = collect_facts(con, store, family) + events = timeline(facts)[:1] + six = " ".join(f"{facts[0].text.rstrip('.')} [{facts[0].id}]." for _ in range(6)) + ask = FakeAsk(default={"text": six}) + summary, lines, extractor, ok = write_prose(facts, events, ask) + assert extractor == "template" + assert "too long: 6 sentences, at most 5" in ask.calls[1][1] + + +def test_in_sample_line(): + assert dos._in_sample_line({"recall": 0.5}) == "" + line = dos._in_sample_line( + { + "in_sample_record": { + "recall": 0.407, + "direction": 0.818, + "n_items": 20, + "n_positions": 27, + "docket": "CMS-2022-0113", + } + } + ) + assert ( + line.startswith(" Tuning-set record: (20 hand-coded comments") and "41%" in line + ) + + +def test_expand_range(): + assert dos._expand_range("99341", ("99341", "99342")) == ("99341",) + assert dos._expand_range("G9999", ("99341",)) == () + assert dos._expand_range("99341-99342", ("99343", "99342", "99341")) == ( + "99341", + "99342", + ) + + +def test_fallbacks_are_reported_per_unit(home_fixture): + con, store, family, _ask = home_fixture + facts = collect_facts(con, store, family) + events = timeline(facts)[:2] + fb: list[str] = [] + write_prose(facts, events, FakeAsk(default=_echo), fallbacks=fb) + assert fb == [] + write_prose(facts, events, None, fallbacks=fb) + assert fb == ["summary", *(f"CY{e.year} {e.kind}" for e in events)] + d = build_dossier(con, store, family) + assert d.fallbacks[0] == "summary" and len(d.fallbacks) == len(d.timeline) + 1