diff --git a/src/llm/dossier.py b/src/llm/dossier.py index 3650be2..4f8f00a 100644 --- a/src/llm/dossier.py +++ b/src/llm/dossier.py @@ -58,7 +58,6 @@ TIMELINE_FLOOR = 4 _STANCE_INTENT = re.compile( r"comment|support|oppos|stakeholder|societ|association|lobby", re.I ) -_ACC = re.compile(r"finds (\d+)% of hand-coded.*?right for (\d+)%") _RANGE = re.compile(r"\b(\d{5})\s*[-\u2013\u2014]\s*(\d{5})\b") _HEADER = ( @@ -193,12 +192,18 @@ class DossierEvidence: docket = f.values.get("docket") if f.kind == "stance_split" else "" if not docket: return f.cite.label - m = _ACC.search(self.accuracy) - if m is None: + # M3: the fact's own measured values, never the sentence's wording + recall, direction = f.values.get("recall"), f.values.get("direction") + if recall is None or direction is None: tail = "accuracy not yet measured" else: - where = "held-out" if "held-out" in self.accuracy else "tuning-set" - tail = f"recall {m[1]}%, direction {m[2]}% on {where} letters" + where = f.values.get("measured_on") or ( + "held-out" if "held-out" in self.accuracy else "tuning-set" + ) + tail = ( + f"recall {round(float(recall) * 100)}%, direction " + f"{round(float(direction) * 100)}% on {where} letters" + ) return f"Our classification of docket {docket} comments — preliminary: {tail}" def _labelled(self, text: str) -> str: diff --git a/src/pfs/cite.py b/src/pfs/cite.py index 6f2a073..664f34f 100644 --- a/src/pfs/cite.py +++ b/src/pfs/cite.py @@ -43,6 +43,36 @@ RVU_FILES_URL = ( "https://www.cms.gov/medicare/payment/fee-schedules/physician/" "pfs-relative-value-files" ) +_CMS = "https://www.cms.gov/" +_OLD = _CMS + "medicare/medicare-fee-for-service-payment/physicianfeesched/" +_MID = ( + _CMS + + "medicaremedicare-fee-service-paymentphysicianfeeschedpfs-relative-value-files/" +) +_NEW = _CMS + "medicare/payment/fee-schedules/physician/pfs-relative-value-files/" +#: M4: each year's own January release page, as CMS's RVU-files page links it +#: (read 2026-11-13; CMS moved the pages several times, so the paths differ) +RVU_RELEASE_URLS: dict[int, str] = { + **{ + y: f"{_OLD}pfs-relative-value-files-items/rvu{y % 100}a" + for y in range(2015, 2020) + }, + **{y: f"{_MID}rvu{y % 100}a" for y in range(2020, 2023)}, + 2023: _CMS + "medicare/medicare-fee-service-payment/physicianfeesched/" + "pfs-relative-value-files/rvu23a", + **{y: f"{_NEW}rvu{y % 100}a" for y in range(2024, 2027)}, +} +#: rule years whose final values on file were loaded from the final rule's +#: Addendum B (no PPRRVU release had been published when they were loaded, +#: 2026-11-11), with the addenda download +FINAL_ADDENDUM_B_URLS: dict[int, str] = { + 2027: _CMS + "files/zip/cy-2027-pfs-final-rule-addenda-updated-11-05-2026.zip", +} +#: the proposed rules' addenda (Addendum B is the proposed RVUs) +PROPOSED_ADDENDUM_B_URLS: dict[int, str] = { + 2026: _CMS + "files/zip/cy-2026-pfs-proposed-rule-addenda.zip", + 2027: _CMS + "files/zip/cy-2027-pfs-proposed-rule-addenda.zip", +} REGS_COMMENT_URL = "https://www.regulations.gov/comment/{id}" SSA_SECTION_URL = "https://www.ssa.gov/OP_Home/ssact/title18/{section}.htm" @@ -200,9 +230,19 @@ def comment_cite(comment_id: str) -> Cite: 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) + """The PFS relative value file of *year*, at that year's own release + page (M4); a year whose final values came from the final rule's + Addendum B, and every proposed value (the NPRM's Addendum B), cite that + addendum. A year with no known page keeps CMS's RVU-files page.""" + if proposed: + label = f"CY{year} proposed rule Addendum B" + url = PROPOSED_ADDENDUM_B_URLS.get(year, RVU_FILES_URL) + elif year in FINAL_ADDENDUM_B_URLS: + label, url = f"CY{year} final rule Addendum B", FINAL_ADDENDUM_B_URLS[year] + else: + label = f"PFS CY{year} RVU file" + url = RVU_RELEASE_URLS.get(year, RVU_FILES_URL) + return Cite("rvu_file", label, url, locator=label) def book_cite(item_key: str, edition_label: str, page_label: str) -> Cite: diff --git a/src/pfs/dossier.py b/src/pfs/dossier.py index 402b01c..0cc353e 100644 --- a/src/pfs/dossier.py +++ b/src/pfs/dossier.py @@ -106,6 +106,8 @@ _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" +#: I4: every stakeholder panel's unit labels are the identity model's +IDENTITY_MARK = "organization type and specialty: model reading, unreviewed" DOSSIER_VERSION = 1 PROSE_PROMPT_VERSION = "prose-v3" #: only the specialties billing at least this share get money, impact and @@ -377,6 +379,7 @@ class _Bib: self._rules: dict[str, tuple[str, int | None]] = {} self._paras: dict[tuple[str, int], str | None] = {} self._ref_urls: dict[tuple[str, str], str] = {} + self._books: dict[str, dict[str, str]] = {} def reference_url(self, kind: str, locator: str) -> str: key = (kind, locator) @@ -422,6 +425,19 @@ class _Bib: self._paras[key] = (row[0] or "") if row else None return self._paras[key] + def book_page(self, item_key: str, label: str) -> str: + """The text of printed page *label* of a licensed book's EPUB (read + to check a paraphrase, never stored); ``""`` when unreadable.""" + if item_key not in self._books: + from pfs.guideline_facts import load_pages + + try: + self._books[item_key] = dict(load_pages(self.store, item_key) or []) + except Exception as exc: # noqa: BLE001 - an unreadable book is no check + log.warning("book %s unreadable: %s", item_key, exc) + self._books[item_key] = {} + return self._books[item_key].get(str(label).strip(), "") + def title(self, item_key: str) -> str: row = ( self.store._con() # noqa: SLF001 @@ -621,12 +637,41 @@ def stance_accuracy_line(ev: Mapping[str, Any] | None) -> str: ) return ( f"Preliminary model classification, measured {scope} ({ev['n_items']} " - f"hand-coded comments, {ev['n_positions']} positions; {where}): it finds " + f"hand-coded comments, {ev['n_positions']} positions; {where}" + f"{_kinds_clause(ev)}): 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." ) +_KIND_WORDS = { + "valuation": "valuation", + "coding": "coding", + "telehealth": "the telehealth-list status", + "other": "other aspects", +} + + +def _kinds_clause(ev: Mapping[str, Any]) -> str: + """M2: which event kinds the measured set holds positions on, and the + family's own kinds (valuation, coding) it has none on, so a count on a + kind the set never measured is read with that in mind.""" + from pfs.stance import heldout_event_kinds + + kinds = list(ev.get("event_kinds") or heldout_event_kinds(ev)) + if not kinds: + return "" + links = sorted(k for k in kinds if k not in _KIND_WORDS) + parts = [] + if links: + noun = "the linked codes" if len(links) > 1 else "the linked code" + parts.append(f"{noun} {_join_and(links)}") + parts += [w for k, w in _KIND_WORDS.items() if k in kinds] + missing = [k for k in ("valuation", "coding") if k not in kinds] + none = f", none on {' or '.join(missing)}" if missing else "" + return f"; its positions are on {_join_and(parts)}{none}" + + def _in_sample_line(ev: Mapping[str, Any], docket: str = "") -> str: """The secondary tuning-set record (`in_sample_record`), as its own sentence; with *docket*, only when the record was measured on that @@ -705,11 +750,44 @@ def _book_edition(bib: _Bib, item_key: str, fallback: str) -> str: return title or fallback -def _origin_facts(con: Any, bib: _Bib, family: Any) -> list[Fact]: +def _origin_problems(bib: _Bib, rows: Sequence[OriginRow], text: str) -> list[str]: + """I3: what a model origin summary gets wrong against what it cites + (``pfs.guideline_facts.paraphrase_problems``): the FR paragraph and the + paragraph stating its reference, or the cited book page when its text + can be read; ``[]`` when there is nothing to check it against.""" + from pfs.guideline_facts import paraphrase_problems + + r = rows[0] + if r.cite_kind == "cpt_book": + passage = bib.book_page(r.item_key, r.page_label) + else: + passage = " ".join( + bib.paragraph(r.item_key, p) or "" + for p in dict.fromkeys(p for p in (r.p_id, r.ref_p_id) if p) + ) + if not passage.strip(): + return [] + return paraphrase_problems(text, passage) + + +def _origin_facts( + con: Any, bib: _Bib, family: Any, review: list[dict] | None = None +) -> list[Fact]: + """Origin and formation facts. A row a model wrote (extractor + ``model:``) is shown flagged "model paraphrase, unreviewed" (I3) and only + when it passes its grounding check against what it cites (polarity and + qualifiers kept); one that fails goes to *review* instead. A statute row + stands only on a final rule (R37).""" groups: dict[tuple, list[OriginRow]] = {} for r in _rows(read_origin, con, family.key): if not _real_reference(r): continue + if ( + r.kind == "statute" + and r.cite_kind == "fr_para" + and bib.rule(r.item_key)[0] != "final" + ): + continue # R37: a proposal's paragraph states no law in force key = ( r.kind, r.reference, @@ -769,8 +847,27 @@ def _origin_facts(con: Any, bib: _Bib, family: Any) -> list[Fact]: 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" + note = "" + if any(r.extractor.startswith("model:") for r in rows): + note = UNREVIEWED + problems = _origin_problems(bib, rows, text) + if problems: + if review is not None: + review.append( + { + "fact_id": "", + "kind": fact_kind, + "reason": "model paraphrase failed its grounding check " + "against what it cites: " + "; ".join(problems), + "text": text, + "cite": asdict(cite), + } + ) + continue out.append( - _draft(fact_kind, year, codes, text, cite, {"origin_kind": kind}, also) + _draft( + fact_kind, year, codes, text, cite, {"origin_kind": kind}, also, note + ) ) return out @@ -909,6 +1006,13 @@ def _guideline_facts(con: Any, bib: _Bib, family: Any) -> list[Fact]: cite, also = fr_para_cite(bib.store, item, p_id), [book, cite] else: cite, also = book, [cite] + if any( + k in prof for k in ("time_threshold_min", "typical_time_min") + ): + # M6: the minutes come from the later book's page, + # so that page is the primary cite + page = also.pop() + cite, also = page, [cite, *also] out.append( _draft( "event", @@ -971,35 +1075,84 @@ def _event_stated(bib: _Bib, e: Any) -> bool: 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".""" + return _stating_sentence(bib, e) is not None + + +def _stating_sentence(bib: _Bib, e: Any) -> str | None: + """The sentence that states the FR lineage row *e* (``_event_stated``; + a telehealth-list row's whole paragraph), else ``None``.""" 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 + return None text = bib.paragraph(e.item_key, e.p_id) if not text or text.lstrip().startswith("Comment:"): - return False + return None 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)) + if _names(text, e.code) and _EVENT_VERB[e.kind].search(text): + return text + return None 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 + return s 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 + return s + return None + + +def _successors_in(sentence: str) -> set[str]: + """The codes *sentence* names as successors: those of its successor + clauses ("replaced them with 99418", "into 99341-99350"), which + ``pfs.lineage`` masks before reading a deletion.""" + from pfs.lineage import FR_CITE_RE, _mask_successors + + text = FR_CITE_RE.sub(" ", _expand_ranges(sentence or "")) + return set(find_codes(text)) - set(find_codes(_mask_successors(text))) + + +def _rvu_years( + con: Any, codes: Sequence[str] +) -> tuple[dict[str, int], dict[str, set[int]], int | None]: + """``(code -> first RVU year, code -> years payable (status A/R/T), the + first RVU year on file)`` for *codes*; empty without ``pfs.rvu``.""" + from pfs.valuation import PAID_STATUSES + + if not codes: + return {}, {}, None + marks = ",".join("?" * len(codes)) + paid = ",".join(f"'{s}'" for s in sorted(PAID_STATUSES)) + try: + rows = con.execute( + f"SELECT hcpcs, year, max(CASE WHEN status_code IN ({paid}) THEN 1 ELSE 0 END) " + f"FROM pfs.rvu WHERE hcpcs IN ({marks}) GROUP BY hcpcs, year", + list(codes), + ).fetchall() + lo = con.execute("SELECT min(year) FROM pfs.rvu").fetchone()[0] + except Exception as exc: # noqa: BLE001 + if is_missing_table_error(exc): + return {}, {}, None + raise + first: dict[str, int] = {} + payable: dict[str, set[int]] = {} + for code, year, is_paid in rows: + first[code] = min(year, first.get(code, year)) + if is_paid: + payable.setdefault(code, set()).add(year) + return first, payable, lo def _known_codes(con: Any, family: Any) -> set[str]: @@ -1014,9 +1167,31 @@ def _known_codes(con: Any, family: Any) -> set[str]: return known -def _event_facts(con: Any, bib: _Bib, family: Any) -> list[Fact]: +def _event_facts( + con: Any, bib: _Bib, family: Any, review: list[dict] | None = None +) -> list[Fact]: + """The family's lineage events, each a final rule's plain sentence or an + RVU-file change, after the contradiction pass (I8a): a ``deleted`` or + ``disappeared`` event for a code payable in a later RVU year, and a + ``created`` and ``deleted`` pair of one code in one year, are dropped; a + ``replaced_by`` target must be new that year (first in the RVU file) or + named as a successor in the stating sentence, else it is dropped (the + event too when none is left). Each drop goes to *review*.""" since = {ln.target: ln.since or 0 for ln in family.links} known = _known_codes(con, family) + rows = {code: _rows(read_events, con, code) for code in [*family.codes, *since]} + first_seen, payable, rvu_lo = _rvu_years( + con, + sorted( + {c for es in rows.values() for e in es for c in e.to_codes.split()} + | set(rows) + ), + ) + dropped: list[tuple[Any, str]] = [] + + def is_new(code: str, year: int) -> bool: + return rvu_lo is not None and year > rvu_lo and first_seen.get(code, 0) >= year + kept: dict[tuple, Any] = {} # R96: the paragraph the curated membership cites (the coding paragraph, # PETM225D ¶1672) before a recap elsewhere; then the lowest paragraph @@ -1025,25 +1200,85 @@ def _event_facts(con: Any, bib: _Bib, family: Any) -> list[Fact]: def rank(e: Any) -> tuple[bool, int, str]: return ((e.code, e.item_key, e.p_id) not in coding, e.p_id, e.item_key) - for code in [*family.codes, *since]: - for e in _rows(read_events, con, code): + for code, events in rows.items(): + for e in events: 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 + sentence = "" if e.source == "rvu": if e.kind not in _RVU_KINDS: continue - elif e.source != "fr" or not _event_stated(bib, e): + elif e.source != "fr": continue + else: + stated = _stating_sentence(bib, e) + if stated is None: + continue + sentence = stated 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 == "replaced_by" and to: + named = _successors_in(sentence) + bad = [c for c in to if not (is_new(c, e.year) or c in named)] + if bad: + dropped.append( + ( + e, + f"replacement target{'s' if len(bad) > 1 else ''} " + f"{_join_and(bad)} neither new in CY{e.year} nor named " + "as a successor in the stating sentence", + ) + ) + to = tuple(c for c in to if c not in bad) 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 rank(e) < rank(prior[0]): kept[key] = (e, to, frm) + # the contradiction pass (I8a): an ended code that is payable later + for key in list(kept): + code, year, kind, _to, _frm = key + later = sorted(y for y in payable.get(code, ()) if y > year) + if kind in ("deleted", "disappeared") and later: + dropped.append( + (kept.pop(key)[0], f"{code} is payable in the CY{later[0]} RVU file") + ) + # ... and a code created and deleted in one year + both = {(c, y) for c, y, k, _t, _f in kept if k == "created"} & { + (c, y) for c, y, k, _t, _f in kept if k == "deleted" + } + for key in [ + k for k in kept if (k[0], k[1]) in both and k[2] in ("created", "deleted") + ]: + dropped.append( + (kept.pop(key)[0], f"{key[0]} is both created and deleted for CY{key[1]}") + ) + if review is not None: + for e, why in dropped: + cite = ( + rvu_cite(e.year) + if e.source == "rvu" + else fr_para_cite(bib.store, e.item_key, e.p_id) + ) + review.append( + { + "fact_id": "", + "kind": "event", + "reason": f"lineage contradiction: {why}", + "text": event_fact_text( + e.kind, + e.code, + e.year, + to=e.to_codes.split(), + from_=e.from_codes.split(), + note=e.note, + ), + "cite": asdict(cite), + } + ) # 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: @@ -1585,7 +1820,11 @@ def _stance_facts(con: Any, family: Any) -> list[Fact]: ) base = {"docket": r.period} if ev: - base.update(recall=ev["recall"], direction=ev["direction"]) + base.update( + recall=ev["recall"], + direction=ev["direction"], + measured_on="tuning-set" if ev.get("in_sample", True) else "held-out", + ) for key, c in events.items(): slug = key.split(":")[-1] s, m, o, u = ( @@ -1645,6 +1884,30 @@ def _stance_facts(con: Any, family: Any) -> list[Fact]: # ── payment, impacts, money, seats ────────────────────────────────── +def in_family_window( + rows: Sequence[Any], family: Any, ends: Mapping[str, int] | None = None +) -> list[Any]: + """*rows* (payment, utilization or PSPS rows: a ``code`` or ``hcpcs`` + and a ``year``) as far as they belong to *family*: a member code's every + year, a link code's only from its ``since`` and before its end (*ends*: + target -> the year a later rule replaces it). I2: the one window the + payment table, the utilization panel and the PSPS money all use, so a + linked code's billing before it joined the family (G2211's office E/M + volume) is never counted as the family's.""" + ends = ends or {} + since = {ln.target: ln.since or 0 for ln in family.links} + + def code(r: Any) -> str: + return getattr(r, "code", None) or r.hcpcs + + return [ + r + for r in rows + if (code(r) not in since or r.year >= since[code(r)]) + and r.year < ends.get(code(r), 10**6) + ] + + def _payment_rows( con: Any, family: Any, ends: Mapping[str, int] | None = None ) -> list[Any]: @@ -1654,22 +1917,18 @@ def _payment_rows( same NPRM proposed to replace is not shown (R96).""" from pfs.valuation import valuation - ends = ends or {} - 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 + con, + [*family.codes, *(ln.target for ln in family.links)], + 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]) - and r.year < ends.get(r.code, 10**6) - ] + return in_family_window(rows, family, ends) def _payment_row(r: Any) -> PaymentRow: @@ -1801,7 +2060,11 @@ def _psps_cite(psps: Sequence[Any], year: int) -> Cite: def _money_facts( - year: int, money: Sequence[Any], psps: Sequence[Any], family: Any + year: int, + money: Sequence[Any], + psps: Sequence[Any], + family: Any, + link_cites: Mapping[str, Cite] | None = None, ) -> list[Fact]: out: list[Fact] = [] if not money: @@ -1809,6 +2072,16 @@ def _money_facts( cite = _psps_cite(psps, year) also = [rvu_cite(year - 1), rvu_cite(year)] if money[0].new_codes: + # M4: new payment a curated link brings cites the paragraph that + # links it (the RVU file does not list a modifier such as B1) + linked = [ + (link_cites or {})[c] for c in money[0].new_codes if c in (link_cites or {}) + ] + new_cite, new_also = ( + (linked[0], [*linked[1:], rvu_cite(year)]) + if linked + else (rvu_cite(year), []) + ) out.append( _draft( "money", @@ -1816,8 +2089,9 @@ def _money_facts( 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), + new_cite, {}, + new_also, ) ) ranked = [m for m in money if m.share >= MIN_SHARE and m.specialty != "NONE"] @@ -1826,20 +2100,29 @@ def _money_facts( suppressed = ( " (CMS suppresses lines under 11 services)" if m.lower_bound else "" ) + # I1: the change covers only the codes paid in both years; "at + # least" only when a count behind it was suppressed + partial = round(m.delta_services) < round(m.services) 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 - ) + amount = money_change(m.delta_total, lower_bound=m.delta_lower_bound) if m.delta_pct is not None: - change += f" ({m.delta_pct:+.1%})" + amount += f" ({m.delta_pct:+.1%})" + change = ( + f"on the {m.delta_services:,.0f} of those {m.services:,.0f} services " + f"whose codes were paid in both CY{year - 1} and CY{year}, the final " + f"payment change was {amount}" + if partial + else f"the final payment change on those services was {amount}" + ) 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)) + values["delta_services"] = round(m.delta_services) if m.delta_pct is not None: values["delta_pct"] = f"{m.delta_pct:+.1%}" out.append( @@ -1855,22 +2138,64 @@ def _money_facts( ) ) if m.proposed_delta_total is not None: + amount = money_change( + m.proposed_delta_total, lower_bound=m.proposed_lower_bound + ) + on = ( + f"on the {m.proposed_services:,.0f} of {m.specialty}'s " + f"{m.services:,.0f} services whose codes had a CY{year} proposed " + f"payment and a CY{year - 1} final payment was" + if round(m.proposed_services) < round(m.services) + else f"on the same services for {m.specialty} was" + ) 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)}.", + f"For CY{year}, the proposed payment change {on} {amount}.", cite, - {"proposed_delta_total": round(abs(m.proposed_delta_total))}, + { + "proposed_delta_total": round(abs(m.proposed_delta_total)), + "proposed_services": round(m.proposed_services), + "services": round(m.services), + }, also, ) ) return out +def unpriced_moves( + year: int, payment: Sequence[Any], psps: Sequence[Any], family: Any +) -> str: + """I1: the gap line of a merger year: the family's predecessor codes last + paid in CY(year-1), whose services moved to successor codes that are not + priced against them (no crosswalk pricing yet), with their volume in the + latest PSPS year before; ``""`` when none ended that year.""" + from pfs.stakes import _latest_services + + paid = {(r.code, r.year) for r in payment if not r.proposed} + ended = sorted( + m.code + for m in family.members + if m.role == "predecessor" + and (m.code, year - 1) in paid + and (m.code, year) not in paid + ) + per = _latest_services(psps, year) + n = sum(v for c in ended for v, _lb in per.get(c, {}).values()) + if not ended or not n: + return "" + many = len(ended) > 1 + return ( + f"CY{year}: {compact(ended)}, last paid in CY{year - 1} ({n:,.0f} services in " + f"the latest PSPS year before), {'are' if many else 'is'} not priced " + f"against {'their' if many else 'its'} successor codes; the CY{year} money " + "facts cover only codes paid in both years." + ) + + def _roster_cite(row: Any, year: int) -> Cite: from pfs.seats import snapshot_url @@ -1960,6 +2285,11 @@ class _Assembly: money: dict[int, list[Any]] impacts: list[Any] billing: dict[int, set[str]] + #: rows held out of the facts for the S2 review queue (a lineage + #: contradiction, a model paraphrase that fails its check) + review: list[dict] = field(default_factory=list) + #: computed gap lines of the assembly (an unpriced merger, I1) + gaps: list[str] = field(default_factory=list) def _assemble( @@ -1970,11 +2300,12 @@ def _assemble( bib = _Bib(store) rounds = _rows(read_rounds, con, family.key) ends = _link_ends(bib, family) + review: list[dict] = [] drafts: list[Fact] = [ *ends, - *_origin_facts(con, bib, family), + *_origin_facts(con, bib, family, review), *_guideline_facts(con, bib, family), - *_event_facts(con, bib, family), + *_event_facts(con, bib, family, review), *_link_facts(bib, family), *_round_facts(bib, rounds), *_pe_facts(bib, rounds), @@ -1996,11 +2327,17 @@ def _assemble( payment = _payment_rows(con, family, end_years) drafts += _payment_facts(payment) codes = [*family.codes, *(ln.target for ln in family.links)] - psps = _rows(read_psps, con, codes) + psps = in_family_window(_rows(read_psps, con, codes), family, end_years) exposures = _rows(read_becomes_payable, con, family.codes) final_years = {r.year for r in payment if not r.proposed} + link_cites = { + f.codes[0]: f.cite + for f in drafts + if f.kind == "link" and "link_kind" in f.values + } money: dict[int, list[Any]] = {} billing: dict[int, set[str]] = {} + gaps: list[str] = [] for y in years: billing[y] = { s for s, share in billing_share(psps, year=y).items() if share >= MIN_SHARE @@ -2009,7 +2346,9 @@ def _assemble( money[y] = money_by_specialty( payment, psps, year=y, links=family.links, exposures=exposures ) - drafts += _money_facts(y, money[y], psps, family) + drafts += _money_facts(y, money[y], psps, family, link_cites) + if line := unpriced_moves(y, payment, psps, family): + gaps.append(line) impacts = _impact_rows(con, years) drafts += _impact_facts(bib, impacts, billing) seats = _rows(read_seats, con) @@ -2050,6 +2389,8 @@ def _assemble( money, impacts, billing, + review, + gaps, ) @@ -2234,6 +2575,10 @@ def coverage( f"one of its {len(family.pair_phrases)} curated phrases; other comments " "that mention the family await review." ) + out.append( + "Commenter organization type and specialty are model readings; " + "identity labels not yet measured." + ) return out @@ -2400,12 +2745,19 @@ def _cms_target(f: Fact, groups: Mapping[tuple[int, str], Any]) -> str: return "comments" -def timeline(facts: Sequence[Fact]) -> list[TimelineEvent]: +def timeline( + facts: Sequence[Fact], codes: Sequence[str] | None = None +) -> 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 attach to the event of their year they speak to; CMS's summaries to the event their Comment is about (``_cms_target``), else to the year's - ``comments`` event. Each event's ``what_changed`` is its template line.""" + ``comments`` event. With the family's member *codes* (M1), a count about + the family's own codes (valuation, coding, telehealth) never sits under + an event that names none of them (G0318's telehealth-list line): it goes + to the year's ``comments`` event. Each event's ``what_changed`` is its + template line.""" + members = set(codes) if codes is not None else None groups: dict[tuple[int, str], list[Fact]] = {} for f in facts: k = _tl_kind(f) @@ -2414,9 +2766,16 @@ def timeline(facts: Sequence[Fact]) -> list[TimelineEvent]: stance: dict[tuple[int, str], list[str]] = {} cms: dict[tuple[int, str], list[str]] = {} + def about_members(key: tuple[int, str]) -> bool: + return ( + members is None + or key[1].startswith("link:") + or any(c in members for f in groups[key] for c in f.codes) + ) + def target(year: int, prefer: Sequence[str]) -> tuple[int, str]: for k in prefer: - if (year, k) in groups: + if (year, k) in groups and about_members((year, k)): return (year, k) groups.setdefault((year, "comments"), []) return (year, "comments") @@ -2576,6 +2935,7 @@ def write_prose( replay_model: str | None = None, limit: int = 0, fallbacks: list[str] | None = None, + pending: list[str] | None = None, ) -> tuple[str, dict[int, str], str, bool]: """The summary and one line per timeline event. The summary and the lines of valuation and comments events are template copy (R95). For any @@ -2590,7 +2950,9 @@ def write_prose( for *replay_model* is replayed. Returns ``(summary, lines by event index, extractor, check_passed)``; nothing unchecked is ever returned. A *fallbacks* list receives the model units that fell back to template - copy ("CY2023 deleted").""" + copy ("CY2023 deleted"); a *pending* list (M9) those of them the ledger + holds no answer for and that were not asked (a replay after the facts + or the prompt changed, a --limit cut).""" by_id = {f.id: f for f in facts} model = getattr(ask, "model", None) if ask is not None else replay_model texts: list[str] = [template_summary(facts, events)] @@ -2616,6 +2978,8 @@ def write_prose( out = _ask_checked(ask, EVENT_SYSTEM, user, allowed, 2) if log is not None: log.put(unit, h, model, PROSE_PROMPT_VERSION, out) + elif pending is not None: + pending.append(f"CY{e.year} {e.kind}") # a recorded answer is re-checked: nothing unchecked is returned if out is not None and not _problems(out["text"], allowed, 2): texts.append(out["text"]) @@ -2651,6 +3015,9 @@ def _unit_dict(u: Any) -> dict: "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), + # I4: how the labels were read + "basis": dict(u.bases), + "extractor": list(u.extractors), } @@ -2711,6 +3078,7 @@ def _stakeholders(con: Any, family: Any, a: _Assembly) -> list[dict]: "event_key": key, "event_text": event_label(slug), "accuracy": acc, + "identity": IDENTITY_MARK, "roster_year": ry, "roster_note": note.strip(" ()"), "units": [_unit_dict(u) for u in units], @@ -2729,6 +3097,7 @@ def stakeholder_lines(d: Dossier) -> list[str]: f"RUC roster {p['roster_year'] or 'not captured'})" ) out.append(f" {p['accuracy']}") + out.append(f" {p.get('identity', IDENTITY_MARK)}") out.append( " org type | specialty | commenters | stance | expected (reason) | " "billing share | payment change | RUC seats" @@ -2807,6 +3176,23 @@ def _sources( return out +def _dossier_accuracy(classified: Sequence[ReactionRow]) -> str: + """M3: the accuracy sentence of the dossier's counts: one sentence when + every classified docket was measured the same way, else each docket's + own ("For docket X: ..."), never the last docket's for all.""" + lines: dict[str, list[str]] = {} + for r in classified: + ev = _eval(r) + line = stance_accuracy_line(ev) + (_in_sample_line(ev) if ev else "") + lines.setdefault(line, []).append(r.period) + if len(lines) <= 1: + return next(iter(lines), "") + return " ".join( + f"For docket{'s' if len(ds) > 1 else ''} {', '.join(ds)}: {line}" + for line, ds in lines.items() + ) + + def build_dossier( con: Any, store: Any, @@ -2817,17 +3203,18 @@ def build_dossier( log: RunLog | None = None, replay_model: str | None = None, limit: int = 0, + pending: list[str] | None = None, ) -> 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*).""" + *limit*/*pending*).""" 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) + events = timeline(facts, family.codes) fallbacks: list[str] = [] summary, lines, extractor, ok = write_prose( facts, @@ -2837,15 +3224,13 @@ def build_dossier( replay_model=replay_model, limit=limit, fallbacks=fallbacks, + pending=pending, ) 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 = _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 "") + ends = {f.values["link_end"]: f.year for f in a.ends} + util = in_family_window(_rows(read_series, con, codes), family, ends) + acc = _dossier_accuracy(_classified(con, family)) return Dossier( family=family.key, name=family.name, @@ -2860,7 +3245,7 @@ def build_dossier( stakeholders=_stakeholders(con, family, a), governance=list(excerpts), sources=_sources(facts, excerpts), - gaps=coverage(con, store, family, years=a.years), + gaps=coverage(con, store, family, years=a.years) + a.gaps, facts=by_id, built_at=_dt.datetime.now(_dt.UTC) .replace(tzinfo=None) @@ -2868,6 +3253,7 @@ def build_dossier( check_passed=ok, extractor=extractor, review=[{"fact_id": f.id, "reason": f.note} for f in facts if f.note] + + a.review + held_summaries(con, _Bib(store), family), fallbacks=fallbacks, stance_accuracy=acc, diff --git a/src/pfs/stakes.py b/src/pfs/stakes.py index 9166799..f11f595 100644 --- a/src/pfs/stakes.py +++ b/src/pfs/stakes.py @@ -22,9 +22,10 @@ from __future__ import annotations import csv import re +from collections import Counter from dataclasses import dataclass from pathlib import Path -from typing import Any, Sequence +from typing import Any, Mapping, Sequence from pfs.codetables import ( ExposureRow, @@ -290,6 +291,16 @@ class SpecialtyMoney: #: specialty. Their pay change is "new, amount n/a", not a missing value. new_codes: tuple[str, ...] = () delta_note: str = "" + #: I1: the services ``delta_total`` covers (codes with a final payment + #: in both year-1 and year), out of ``services``; a code that ends in + #: year-1 (a merger) counts in ``services`` but not here + delta_services: float = 0.0 + #: True when a service count behind ``delta_total`` was suppressed, so + #: the delta is a lower bound; a shortfall from ended codes never is + delta_lower_bound: bool = False + #: the same for ``proposed_delta_total`` + proposed_services: float = 0.0 + proposed_lower_bound: bool = False def _latest_services(psps: Sequence[PspsRow], year: int) -> dict[str, dict[str, float]]: @@ -398,7 +409,16 @@ def money_by_specialty( proposed[v.code] = v.pay_nf else: final[(v.code, v.year)] = v.pay_nf - services = _latest_services(psps, year) + # I1: a code whose last final payment is before year-1 ended years + # before; its old volume is no longer the family's billing + last: dict[str, int] = {} + for c, y in final: + last[c] = max(y, last.get(c, y)) + services = { + code: per + for code, per in _latest_services(psps, year).items() + if last.get(code, year) >= year - 1 + } new_codes = new_codes_in(exposures, links, year=year) acc: dict[str, dict[str, Any]] = {} for code, per in services.items(): @@ -423,24 +443,25 @@ def money_by_specialty( return num / den if num is not None and den else None out: list[SpecialtyMoney] = [] + + def covered(spec: str, now: Mapping[str, float | None]) -> tuple[float, bool]: + """(services, any suppressed) of *spec* on the codes with a payment + in *now* and a final payment in year-1.""" + cells = [ + (n, lb) + for code, per in services.items() + for s, (n, lb) in per.items() + if s == spec + and now.get(code) is not None + and final.get((code, year - 1)) is not None + ] + return sum(n for n, _lb in cells), any(lb for _n, lb in cells) + + this_year = {c: p for (c, y), p in final.items() if y == year} for spec, a in acc.items(): # services of only the codes that carry a delta, for the per-service mean - d_svc = sum( - n - for code, per in services.items() - for s, (n, _lb) in per.items() - if s == spec - and final.get((code, year)) is not None - and final.get((code, year - 1)) is not None - ) - p_svc = sum( - n - for code, per in services.items() - for s, (n, _lb) in per.items() - if s == spec - and proposed.get(code) is not None - and final.get((code, year - 1)) is not None - ) + d_svc, d_lb = covered(spec, this_year) + p_svc, p_lb = covered(spec, proposed) out.append( SpecialtyMoney( specialty=spec, @@ -456,6 +477,10 @@ def money_by_specialty( proposed_delta_per_service=ratio(a["pd"], p_svc), proposed_delta_total=a["pd"], proposed_delta_pct=ratio(a["pd"], a["pbase"]), + delta_services=d_svc, + delta_lower_bound=d_lb, + proposed_services=p_svc, + proposed_lower_bound=p_lb, ) ) return sorted(out, key=lambda m: (-m.services, m.specialty)) @@ -539,6 +564,11 @@ class StakeholderUnit: share: float delta_total: float | None delta_lower_bound: bool = False + #: I4: how the members' organization type and specialty were read + #: (``pfs.commenter.basis`` -> count) and by which extractor; a + #: ``letterhead_model`` label is the model's, never measured + bases: tuple[tuple[str, int], ...] = () + extractors: tuple[str, ...] = () _PERSON_TYPES = ("individual", "individual_clinician") @@ -610,7 +640,9 @@ def stakeholder_units( ), share=share, delta_total=m.delta_total if m else None, - delta_lower_bound=bool(m and m.lower_bound), + delta_lower_bound=bool(m and m.delta_lower_bound), + bases=tuple(sorted(Counter(c.basis for c in members.values()).items())), + extractors=tuple(sorted({c.extractor for c in members.values()})), ) ) return out diff --git a/src/pfs/stance.py b/src/pfs/stance.py index d161b1e..97d706e 100644 --- a/src/pfs/stance.py +++ b/src/pfs/stance.py @@ -982,6 +982,36 @@ class Scores: return self.cell_agreement >= cell and self.firm_accuracy >= firm +def event_kinds_of(golden: Mapping[str, Any]) -> list[str]: + """The event kinds a golden set holds positions on (M2): the slug of + every event key with at least one hand-coded label other than ``none`` + ("valuation", "coding", "telehealth", "other", or a link code).""" + return sorted( + { + key.split(":")[-1] + for it in golden.get("items") or () + for key, cell in (it.get("cells") or {}).items() + if (cell or {}).get("label", "none") != "none" + } + ) + + +def heldout_event_kinds(ev: Mapping[str, Any]) -> list[str]: + """The event kinds of the packaged golden set a ``stance_eval`` record + was measured on (same family, dockets and held-out flag), for a record + stamped before ``event_kinds`` was; ``[]`` when none matches.""" + dockets = sorted(ev.get("dockets") or [ev.get("docket", "")]) + for path in sorted((Path(__file__).resolve().parent / "golden").glob("*.json")): + data = json.loads(path.read_text(encoding="utf-8")) + if ( + data.get("family") == ev.get("family") + and sorted(golden_dockets(data)) == dockets + and bool(data.get("in_sample", True)) == bool(ev.get("in_sample", True)) + ): + return event_kinds_of(data) + return [] + + def golden_dockets(golden: Mapping[str, Any]) -> list[str]: """The dockets a golden file covers: ``"dockets": [...]`` (multi-docket format, each item names its own ``"docket"``) or the single ``"docket"``.""" diff --git a/tests/llm/test_dossier.py b/tests/llm/test_dossier.py index 9d20f49..7a59fc1 100644 --- a/tests/llm/test_dossier.py +++ b/tests/llm/test_dossier.py @@ -2,6 +2,7 @@ from __future__ import annotations +import dataclasses import logging from dataclasses import replace @@ -72,7 +73,12 @@ def _dossier(extra=(), accuracy=ACC): 4, "stance_split", "Of 3 CY2023 commenters we classified, 2 supported and 1 opposed. " + ACC, - values={"docket": "CMS-2022-0113"}, + values={ + "docket": "CMS-2022-0113", + "recall": 0.792, + "direction": 0.737, + "measured_on": "held-out", + }, ), _fact(5, "cms_summary", "CMS reported that commenters supported it."), _fact( @@ -555,18 +561,27 @@ def test_stance_label_carries_the_accuracy_caveat(replica): def test_stance_label_variants(): + """M3: the label reads the fact's own measured values, never the wording + of the accuracy sentence.""" base = _dossier() facts = tuple(base.facts.values()) mk = lambda acc: DossierEvidence( # noqa: E731 "F", "N", "u", "[F4]", facts, (), accuracy=acc ) - label = lambda ev: ev._label(base.facts["F4"]) # noqa: E731 - assert label(mk("")).endswith("preliminary: accuracy not yet measured") - tuned = ( - "Preliminary model classification, measured on the tuning set (20 " - "hand-coded comments, 27 positions; X): it finds 41% of hand-coded " - "positions, and the direction is right for 82% of those it finds." - ) - assert label(mk(tuned)).endswith("recall 41%, direction 82% on tuning-set letters") + f4 = base.facts["F4"] + + def label(values, acc=ACC): + return mk(acc)._label(dataclasses.replace(f4, values=values)) + + assert label({"docket": "D"}).endswith("preliminary: accuracy not yet measured") + tuned = { + "docket": "D", + "recall": 0.407, + "direction": 0.818, + "measured_on": "tuning-set", + } + assert label(tuned).endswith("recall 41%, direction 82% on tuning-set letters") + # a reworded accuracy sentence changes nothing + assert label(f4.values, acc="Reworded.") == STANCE_LABEL # the summary tag resolves to the same label assert f"[{STANCE_LABEL}]" in mk(ACC).payload()["summary"] diff --git a/tests/pfs/test_cite.py b/tests/pfs/test_cite.py index 526d0ab..e67d1f9 100644 --- a/tests/pfs/test_cite.py +++ b/tests/pfs/test_cite.py @@ -106,11 +106,39 @@ def test_comment_cite(): 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_rvu_cite_names_the_years_own_file(): + """M4: each year's own release page (CMS's links, read 2026-11-13), not + one landing page for every year; CY2027's final values on file come from + the final rule's Addendum B, and a proposed value from the NPRM's.""" + from pfs.cite import RVU_FILES_URL + + assert rvu_cite(2023).url.endswith("/pfs-relative-value-files/rvu23a") + assert rvu_cite(2015).url.endswith("/pfs-relative-value-files-items/rvu15a") + assert rvu_cite(2026).url == ( + "https://www.cms.gov/medicare/payment/fee-schedules/physician/" + "pfs-relative-value-files/rvu26a" + ) + final27 = rvu_cite(2027) + assert final27.label == "CY2027 final rule Addendum B" + assert final27.url == ( + "https://www.cms.gov/files/zip/" + "cy-2027-pfs-final-rule-addenda-updated-11-05-2026.zip" + ) + prop27 = rvu_cite(2027, proposed=True) + assert prop27.label == "CY2027 proposed rule Addendum B" + assert prop27.url.endswith("cy-2027-pfs-proposed-rule-addenda.zip") + assert rvu_cite(2026, proposed=True).url.endswith( + "cy-2026-pfs-proposed-rule-addenda.zip" + ) + # a year with no known page keeps the landing page + assert rvu_cite(2009).url == RVU_FILES_URL + assert rvu_cite(2030, proposed=True).label == "CY2030 proposed rule Addendum B" + + def test_book_cite(): c = book_cite("3ANRT854", "CPT Changes 2023", "49") assert (c.kind, c.label, c.item_key, c.url) == ( diff --git a/tests/pfs/test_dossier.py b/tests/pfs/test_dossier.py index 3c8e947..9ef0f2b 100644 --- a/tests/pfs/test_dossier.py +++ b/tests/pfs/test_dossier.py @@ -595,13 +595,12 @@ def test_guideline_facts(home_fixture): assert change.year == 2023 and change.kind == "event" assert "medical decision making or total time" in change.text assert "a time threshold of 15 minutes (CPT 2024 codebook)" in change.text - # dated to the code set that made it: the coding paragraph, CPT Changes, - # and the 2024 book as evidence - assert (change.cite.item_key, change.cite.p_id) == ("PETM225D", 1672) - assert [c.label for c in change.also] == [ - "CPT Changes 2023 p. 48", - "CPT 2024 p. 29", - ] + # dated to the code set that made it (the coding paragraph and CPT + # Changes); M6: the minutes come from the 2024 book page, so that page is + # the primary cite of the numeric clause + assert change.cite.label == "CPT 2024 p. 29" + assert [(c.item_key, c.p_id) for c in change.also][:1] == [("PETM225D", 1672)] + assert [c.label for c in change.also][1:] == ["CPT Changes 2023 p. 48"] assert not [t for t in texts if t.startswith("In the CPT 2024 codebook")] deleted = next(f for f in facts if f.text.startswith("CPT deleted")) assert deleted.text == ( @@ -1420,7 +1419,7 @@ def test_origin_edges(home_fixture): "statute", "section 1834(m) of the Act", None, - "A statute about telehealth.", + "The CPT Editorial Panel deleted the Domiciliary code family.", "fr_para", "PETM225D", 1672, @@ -1441,7 +1440,13 @@ def test_origin_edges(home_fixture): ) 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.") + statute = next( + f + for f in facts + if f.text == "The CPT Editorial Panel deleted the Domiciliary code family." + ) + assert statute.note == dos.UNREVIEWED # a model row is shown flagged (I3) + assert book.note == nopage.note == dos.UNREVIEWED and not removal.note assert statute.also[-1] == Cite( "statute", "section 1834(m) of the Act", @@ -2375,3 +2380,356 @@ def test_edition_line_keeps_a_fact_without_a_basis_and_a_single_code(): f"{head}, 99341 has low medical decision making [F1]. " f"{head}, 99350 is selected on other basis [F2]." ) + + +# ── I8a: the lineage contradiction pass (a PROLONGED-shaped family) ── + + +def _prolonged(con, store): + """Three prolonged-service codes: 99356/99357 end in CY2022 and 99418, + new for CY2023, stays payable; paragraphs shaped like the CY2023 final + rule's (invented wording, no descriptor text).""" + from pfs.curated import CuratedFamily, CuratedMember + + rvu = [ + *((c, y) for c in ("99356", "99357") for y in range(2015, 2023)), + *(("99418", y) for y in range(2023, 2027)), + *((c, y) for c in ("99223", "99238") for y in range(2015, 2027)), + ] + con.executemany( + "INSERT INTO pfs.rvu (hcpcs, status_code, year) VALUES (?, 'A', ?)", rvu + ) + _add_paragraph( + store, + 99101, + "To replace deleted CPT codes 99356 and 99357, the CPT Editorial Panel " + "created CPT code 99418, which is reported with CPT codes 99223 and 99238.", + ) + _add_paragraph( + store, + 99102, + "Effective January 1, 2023, the CPT Editorial Panel deleted CPT code 99356 " + "and CPT code 99357 and replaced them with CPT code 99418.", + ) + _add_paragraph(store, 99103, "CPT code 99357 was created for this year.") + + def ev(code, kind, p_id, to="", source="fr"): + return EventRow( + code, 2023 if kind != "disappeared" else 2024, kind, "", to, + "PETM225D" if source == "fr" else "", p_id, 69700, source, True, "", + ) # fmt: skip + + write_events( + con, + "99418", + [ + ev("99418", "created", 99101), + ev("99418", "deleted", 99101), + ev("99418", "replaced_by", 99102, "99238 99356 99357"), + ev("99418", "disappeared", 0, source="rvu"), + ], + ) + write_events( + con, + "99356", + [ev("99356", "replaced_by", 99101, "99223 99238 99357 99418")], + ) + write_events( + con, + "99357", + [ev("99357", "deleted", 99102), ev("99357", "created", 99103)], + ) + return CuratedFamily( + "PROLONGED", + "Prolonged Services", + (), + tuple( + CuratedMember(c, "member", None, None, "", 0, 0, 0) + for c in ("99356", "99357", "99418") + ), + (), + ) + + +def test_lineage_contradictions_are_dropped_and_queued(home_fixture): + con, store, _family, _ask = home_fixture + fam = _prolonged(con, store) + a = dos._assemble(con, store, fam) + events = sorted(f.text for f in a.facts if f.kind == "event") + assert "99418 was created for CY2023." in events + assert "99418 was deleted for CY2023." not in events + assert not [t for t in events if t.startswith("99418 was replaced")] + assert not [t for t in events if t.startswith("99418 no longer appears")] + assert "99356 was replaced by 99418 for CY2023." in events + assert not [t for t in events if t.startswith("99357 was")] + reasons = sorted(r["reason"] for r in a.review if r["kind"] == "event") + assert reasons == [ + "lineage contradiction: 99357 is both created and deleted for CY2023", + "lineage contradiction: 99357 is both created and deleted for CY2023", + "lineage contradiction: 99418 is payable in the CY2024 RVU file", + "lineage contradiction: 99418 is payable in the CY2025 RVU file", + "lineage contradiction: replacement targets 99223, 99238 and 99357 neither " + "new in CY2023 nor named as a successor in the stating sentence", + "lineage contradiction: replacement targets 99238, 99356 and 99357 neither " + "new in CY2023 nor named as a successor in the stating sentence", + ] + queued = {r["text"] for r in a.review if r["kind"] == "event"} + assert "99418 was deleted for CY2023." in queued + assert all(r["cite"]["label"] for r in a.review if r["kind"] == "event") + + +# ── I3: model origin rows are flagged, grounded and final-rule only ── + + +def _statute(family, summary, item="PETM225D", p_id=99201): + return OriginRow( + family.key, "99341", "statute", "section 1899(c) of the Act", None, + summary, "fr_para", item, p_id, "69700", "87 FR 69700", + "model:x@origin-v1", p_id, + ) # fmt: skip + + +def test_model_origin_rows_are_flagged_grounded_and_final_only(home_fixture): + con, store, family, _ask = home_fixture + _add_paragraph( + store, + 99201, + "Except for services furnished by RHCs and FQHCs, section 1899(c) of the " + "Act requires the Secretary to assign beneficiaries to an ACO based on " + "their utilization of primary care services.", + ) + dropped = ( + "Section 1899(c) of the Act requires the Secretary to assign beneficiaries " + "to an ACO based on their utilization of primary care services." + ) + kept = ( + "Except for RHC and FQHC services, section 1899(c) of the Act requires the " + "Secretary to assign beneficiaries to an ACO based on primary care services." + ) + proposal = "The Act requires prolonged home services reporting under a G-code." + write_origin( + con, + family.key, + [ + _statute(family, dropped), + _statute(family, kept), + _statute(family, proposal, "MZ24MX5S", 880), + ], + ) + d = build_dossier(con, store, family) + texts = {f.text: f for f in d.facts.values() if f.kind == "origin"} + assert dropped not in texts and proposal not in texts + assert texts[kept].note == dos.UNREVIEWED + assert {"fact_id": texts[kept].id, "reason": dos.UNREVIEWED} in d.review + held = [r for r in d.review if r.get("text") == dropped] + assert len(held) == 1 and "qualifier" in held[0]["reason"] + assert held[0]["cite"]["p_id"] == 99201 + assert not [r for r in d.review if r.get("text") == proposal] + # deterministic rows (guidance, lineage) carry no note + assert all( + not f.note + for f in d.facts.values() + if f.kind == "origin" and f.text.startswith("CMS guidance for") + ) + + +# ── I2: link codes count only from their ``since`` ────────────────── + + +def test_link_codes_are_windowed_by_since_everywhere(home_fixture): + """G2211 joins the family in CY2026: its 2024 office billing is neither + utilization nor PSPS money of this family (one helper for all three).""" + from pfs import utilization as util + from pfs.codetables import PspsRow, write_psps + + con, store, family, _ask = home_fixture + util.write( + con, + 2024, + [ + util.UtilizationRow(2024, code, "", "N", "O", 10, 10, n, 0, 0, 1, 1, 1, "d", "k") + for code, n in (("G2211", 9_000_000.0), ("99341", 100.0)) + ], + ) # fmt: skip + write_psps( + con, + 2025, + "G2211", + [PspsRow(2025, "G2211", "08", "Family Practice", 5_000_000.0, None, None, "psps", "PSPSKEY1", 5_000_000.0, 0)], + ) # fmt: skip + d = build_dossier(con, store, family) + assert ("G2211", 2024) not in {(r.hcpcs, r.year) for r in d.utilization} + assert ("99341", 2024) in {(r.hcpcs, r.year) for r in d.utilization} + money = [f for f in d.facts.values() if f.kind == "money" and f.year == 2026] + assert money and not [f for f in money if "5,0" in f.text] + # the payment table keeps the same window + assert all(p.year >= 2026 for p in d.payment if p.code == "G2211") + + +# ── I1: a merger year's money states the services its change covers ── + + +def test_merger_year_money_states_its_coverage_and_the_unpriced_move(home_fixture): + from pfs.codetables import PspsRow, write_psps + + con, store, family, _ask = home_fixture + write_psps( + con, + 2022, + "99343", + [PspsRow(2022, "99343", "08", "Family Practice", 3000.0, None, None, "psps", "PSPSKEY1", 3000.0, 0)], + ) # fmt: skip + d = build_dossier(con, store, family) + fp = next( + f + for f in d.facts.values() + if f.kind == "money" and f.year == 2023 and "FAMILY PRACTICE" in f.text + ) + # 99341 and 99350 were paid in both years (4,000 services); 99343 ended + assert ( + "on the 4,000 of those 7,000 services whose codes were paid in both CY2022 " + "and CY2023, the final payment change was" in fp.text + ) + assert ( + "a cut of at least" not in fp.text and "an increase of at least" not in fp.text + ) + assert fp.values["delta_services"] == 4000 + assert check_prose(f"{fp.text} [{fp.id}]", d.facts) == [] + assert ( + "CY2023: 99324–99328, 99334–99337, 99339, 99340 and 99343, last paid in " + "CY2022 (3,000 services in the latest PSPS year before), are not priced " + "against their successor codes; the CY2023 money facts cover only codes " + "paid in both years." in d.gaps + ) + # a year whose codes were all paid in both years keeps the short wording + later = next( + f + for f in d.facts.values() + if f.kind == "money" and f.year == 2027 and "FAMILY PRACTICE" in f.text + ) + assert "the final payment change on those services was" in later.text + + +def test_unpriced_moves_of_one_code_and_of_none(home_fixture): + from types import SimpleNamespace as NS + + con, store, family, _ask = home_fixture + fam = NS(members=[NS(code="A", role="predecessor"), NS(code="B", role="base")]) + pay = [ + NS(code="A", year=2022, proposed=False), + NS(code="B", year=2023, proposed=False), + ] + from pfs.codetables import PspsRow + + psps = [PspsRow(2022, "A", "08", "Family Practice", 5.0, None, None, "d", "K")] + assert dos.unpriced_moves(2023, pay, psps, fam).startswith( + "CY2023: A, last paid in CY2022 (5 services in the latest PSPS year before), " + "is not priced against its successor codes" + ) + assert dos.unpriced_moves(2024, pay, psps, fam) == "" + + +# ── I4: the stakeholder panel says its labels are model readings ───── + + +def test_stakeholder_labels_are_marked_model_readings(home_fixture): + con, store, family, _ask = home_fixture + d = build_dossier(con, store, family) + panel = d.stakeholders[0] + assert panel["identity"] == ( + "organization type and specialty: model reading, unreviewed" + ) + unit = panel["units"][0] + assert set(unit) >= {"basis", "extractor"} + assert sum(unit["basis"].values()) == unit["n_commenters"] + assert all(isinstance(e, str) for e in unit["extractor"]) + lines = dos.stakeholder_lines(d) + assert lines.count( + " organization type and specialty: model reading, unreviewed" + ) == len(d.stakeholders) + assert ( + "Commenter organization type and specialty are model readings; identity " + "labels not yet measured." in d.gaps + ) + + +# ── M1: a stance count sits under an event about the family's codes ── + + +def test_stance_is_never_filed_under_a_link_codes_list_event(): + facts = [ + _f("F1", "event", 2023, "G0318 is named in a telehealth-list paragraph of the CY2023 rule.", ("G0318",), event_kind="telehealth_list"), + _f("F2", "stance_split", 2023, "Of 7 CY2023 commenters we classified on the telehealth-list status of the family's codes, 4 supported.", event_key="HV:2023:telehealth"), + _f("F3", "event", 2024, "99341 is named in a telehealth-list paragraph of the CY2024 rule.", ("99341",), event_kind="telehealth_list"), + _f("F4", "stance_split", 2024, "Of 2 CY2024 commenters we classified on the telehealth-list status of the family's codes, 2 supported.", event_key="HV:2024:telehealth"), + ] # fmt: skip + events = {(e.year, e.kind): e for e in timeline(facts, codes=("99341",))} + assert events[(2023, "telehealth_list")].stance_fact_ids == () + assert events[(2023, "comments")].stance_fact_ids == ("F2",) + assert events[(2024, "telehealth_list")].stance_fact_ids == ("F4",) + + +# ── M2/M3: which positions the accuracy covers; one line per method ── + + +def test_accuracy_line_says_which_event_kinds_the_set_covers(): + ev = { + "recall": 0.792, "direction": 0.737, "n_items": 20, "n_positions": 24, + "family": "HOME-VISITS", "dockets": ["CMS-2025-0304", "CMS-2026-2377"], + "in_sample": False, + } # fmt: skip + want = ( + "CMS-2025-0304, CMS-2026-2377; its positions are on the linked codes B1, " + "B2 and G2211, the telehealth-list status and other aspects, none on " + "valuation or coding): it finds 79%" + ) + # stamped by stance --write, or read off the packaged held-out set + stamped = dos.stance_accuracy_line( + {**ev, "event_kinds": ["B1", "B2", "G2211", "other", "telehealth"]} + ) + assert want in stamped + assert want in dos.stance_accuracy_line(ev) + alone = dos.stance_accuracy_line({**ev, "event_kinds": ["valuation", "coding"]}) + assert "its positions are on valuation and coding)" in alone + # an unknown set names no kinds + assert "its positions" not in dos.stance_accuracy_line({**ev, "dockets": ["X"]}) + + +def test_dossier_accuracy_names_each_method_once(home_fixture): + con, store, family, _ask = home_fixture + from pfs.codetables import read_reaction, replace_reaction_rows + + rows = read_reaction(con, family.key) + d1 = next(r for r in rows if r.n_classified is not None) + other = json.dumps({**json.loads(d1.stance_eval), "recall": 0.5}) + replace_reaction_rows( + con, + family.key, + [dataclasses.replace(d1, period="CMS-2099-0001", stance_eval=other)], + ) + acc = build_dossier(con, store, family).stance_accuracy + assert acc.count("Preliminary model classification") == 2 + assert "For docket CMS-2022-0113:" in acc and "For docket CMS-2099-0001:" in acc + ours = [f for f in collect_facts(con, store, family) if f.kind == "stance_split"] + assert {f.values["measured_on"] for f in ours} == {"held-out"} + + +def test_link_driven_new_payment_cites_the_link_paragraph(home_fixture): + """M4: the RVU file of CY2027 does not list modifiers B1/B2; new payment + a curated link brings cites the paragraph that links it.""" + con, store, family, _ask = home_fixture + facts = collect_facts(con, store, family) + new = { + f.year: f for f in facts if f.kind == "money" and "gained new payment" in f.text + } + assert (new[2023].cite.item_key, new[2023].cite.p_id) == ("PETM225D", 1694) + assert new[2023].also[-1].label == "PFS CY2023 RVU file" + assert {(c.item_key, c.p_id) for c in (new[2027].cite, *new[2027].also)} >= { + ("JCWARTJD", 1168), + ("JCWARTJD", 1205), + } + payment27 = next(f for f in facts if f.kind == "payment" and f.year == 2027) + assert payment27.cite.label in ( + "CY2027 final rule Addendum B", + "CY2027 proposed rule Addendum B", + ) diff --git a/tests/pfs/test_stakes.py b/tests/pfs/test_stakes.py index 733c36f..1f3a747 100644 --- a/tests/pfs/test_stakes.py +++ b/tests/pfs/test_stakes.py @@ -369,6 +369,34 @@ def test_missing_year_gives_none_delta_but_counts_in_share(): assert ca.new_payment is True +def test_the_delta_states_the_services_it_covers(): + """I1: a merger year. B ends in CY2022 (its services move to successors + that are not priced against it); C ended long before and is no longer + the family's billing; the delta covers A's services only, and its "at + least" comes from suppression on A, never from B's shortfall.""" + payment = [ + val("A", 2022, 100.0), + val("A", 2023, 90.0), + val("A", 2023, 95.0, proposed=True), + val("B", 2022, 50.0), + val("C", 2019, 5.0), + ] + psps = [ + ps(2022, "A", "Family Practice", 10.0), + PspsRow(2022, "B", "08", "Family Practice", None, None, 5.0, "d", "K", 30.0, 2), + ps(2019, "C", "Family Practice", 500.0), + ] + (m,) = money_by_specialty(payment, psps, year=2023) + assert m.services == 40.0 and m.lower_bound is True + assert (m.delta_services, m.delta_total, m.delta_lower_bound) == ( + 10.0, + -100.0, + False, + ) + assert (m.proposed_services, m.proposed_delta_total) == (10.0, -50.0) + assert m.proposed_lower_bound is False + + def test_proposed_vs_final_delta_kept_apart(): payment = [ val("A", 2026, 100.0), @@ -832,8 +860,9 @@ _MONEY = [ 0.2, delta_pct=-0.03, lower_bound=True, + delta_lower_bound=True, ), - SpecialtyMoney("DERMATOLOGY", 1.0, None, None, 0.001), + SpecialtyMoney("DERMATOLOGY", 1.0, None, None, 0.001, lower_bound=True), ]