Files
stack/tests/pfs/test_dossier.py

2823 lines
97 KiB
Python
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
"""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") == ""
def test_cms_summary_template():
text = cms_summary_text(
"The majority of commenters supported our proposal.",
2023,
"final",
"majority",
"acknowledged",
"support",
)
assert text == (
'In the CY2023 final rule, CMS summarized: "The majority of commenters '
"supported our proposal.\" CMS's quantifier: a majority of commenters. "
"CMS's response: acknowledged the comments. Stance of CMS's summary "
"(model reading, unreviewed): support."
)
# no quantifier: the clause is left out; an undetermined action reads
# "unclassified" (coordinator wording, lex page)
assert cms_summary_text("x", 2005, "final", "unspecified", "unclear", "mixed") == (
'In the CY2005 final rule, CMS summarized: "x" CMS\'s response is '
"unclassified. Stance of CMS's summary (model reading, unreviewed): mixed."
)
assert cms_summary_text("x", 2005, "final", "one", "unclear", "unclear") == (
'In the CY2005 final rule, CMS summarized: "x" CMS\'s quantifier: one '
"commenter. CMS's response is unclassified. Stance of CMS's summary "
"(model reading, unreviewed): unclear."
)
assert cms_summary_text("x", 2005, "final", "", "not_finalized", "oppose") == (
'In the CY2005 final rule, CMS summarized: "x" CMS\'s response: not '
"finalized. Stance of CMS's summary (model reading, unreviewed): oppose."
)
def test_comment_first_sentence_is_cms_words_without_cpt_text():
para = (
"Comment: One commenter requested clarification on CPT codes 99347 and "
"99348 ( Descriptor (two of three)) and ( printed page 84506) more. "
"Second sentence."
)
assert dos.comment_first_sentence(para) == (
"One commenter requested clarification on CPT codes 99347 and 99348 "
"[CPT descriptor omitted] and more."
)
long = "Comment: " + "word " * 100 + "end."
first = dos.comment_first_sentence(long)
assert len(first) <= 300 and first.endswith("\u2026")
assert dos.comment_first_sentence("") == ""
assert (
dos.strip_descriptors("codes (99341-99350) stay") == "codes (99341-99350) stay"
)
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 was unclear."
)
assert stance_split_text(1, 2023, "x", 1, 0, 0, 0) == (
"Of 1 CY2023 commenter we classified on x, 1 supported, 0 asked for "
"modifications, 0 opposed and 0 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]
first = next(
f
for f in facts
if f.text.startswith("In the earliest CPT edition on file (2022), 99341")
)
assert first.text == (
"In the earliest CPT edition on file (2022), 99341 is selected on history, "
"examination and medical decision making, with straightforward medical "
"decision making and a typical time of 20 minutes."
)
assert first.kind == "event" # never formation (R96)
change = next(
f for f in facts if f.text.startswith("From the CY2023 code set, 99341")
)
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 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 == (
"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"]
majority = next(
f for f in cms if (f.cite.item_key, f.cite.p_id) == ("PETM225D", 1679)
)
# CMS's own words, CMS's quantifier and the response action read by rule;
# the model's stance only as an unreviewed reading (R94)
assert majority.text == (
'In the CY2023 final rule, CMS summarized: "The majority of commenters '
"supported our proposal to accept the RUC-recommended RVUs for all of the "
"Home or Residence Services codes.\" CMS's quantifier: a majority of "
"commenters. CMS's response: acknowledged the comments. Stance of CMS's "
"summary (model reading, unreviewed): support."
)
assert majority.values["model_reading_unreviewed"] == "support"
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 summarized" 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 RUC that valued CY2023 met in 2022), the "
"Primary Care Rotating Seat is a rotating seat." in seats
)
assert (
"The 2026 CPT Editorial Panel roster (the Panel of 2026, for CY2027) lists "
"12 seats for national medical specialty societies." 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({2026}, 2027, "CPT_PANEL") == (
2026,
" (the Panel of 2026, for CY2027)",
)
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 not hasattr(d.payment[0], "description") # AMA text never kept
assert {(p.code, p.year) for p in d.payment if p.code == "99343"} == {
("99343", y) for y in range(2015, 2023)
}
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 _eligible(events):
return [e for e in events if not dos.template_only(e.kind)]
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+template"
assert len(lines) == len(events)
ids = {f.id: f for f in facts}
# the summary and the valuation and comments lines are template copy (R95)
assert summary == template_summary(facts, events)
for i, e in enumerate(events):
if dos.template_only(e.kind):
assert lines[i] == template_event_line(e, ids)
assert all(check_prose(line, ids) == [] for line in lines.values())
assert len(ask.calls) == len(_eligible(events))
prompts = "".join(u for _s, u in ask.calls)
# unreviewed paraphrases, our counts and CMS's summaries never reach it
assert "Fixture paraphrase" not in prompts
assert "we classified" not in prompts and "CMS summarized" not in prompts
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(_eligible(events)) # 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 = _eligible(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 == "model:fake-14b+template"
assert ok and len(ask.calls) == 2
def test_mixed_prose_extractor(home_fixture):
con, store, family, _ask = home_fixture
facts = collect_facts(con, store, family)
events = _eligible(timeline(facts))[:2]
seen = []
def only_first(system, user):
seen.append(user)
return _echo(system, user) if len(seen) == 1 else {"text": "x"}
fb: list[str] = []
write_prose(facts, events, FakeAsk(default=only_first), fallbacks=fb)
assert fb == [f"CY{events[1].year} {events[1].kind}"]
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 = _eligible(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[1][2] == template_event_line(events[2], {f.id: f for f in facts})
second = write_prose(facts, events, ask, log=RunLog(tmp_path / "prose.jsonl"))
assert len(ask.calls) == 3 # the one 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) == 3
def test_unchecked_model_text_is_never_returned(home_fixture):
con, store, family, _ask = home_fixture
facts = collect_facts(con, store, family)
events = _eligible(timeline(facts))[:1]
# numbers no cited fact carries
fid = events[0].fact_ids[0]
ask = FakeAsk(default=lambda s, u: {"text": f"99341 was paid $999.99 [{fid}]."})
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
# M11: the span of the evidence on file, named for what it is
assert d.years_active == d.years_on_file == "CY2008–CY2027"
assert Dossier.from_json(d.to_json()).years_on_file == "CY2008–CY2027"
legacy = json.loads(d.to_json())
del legacy["years_on_file"]
assert Dossier.from_json(json.dumps(legacy)).years_on_file == "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(
r.cites["final_work_rvu"].url for r in d.rounds if r.final_work_rvu is not None
)
r = {(x.code, x.item_key): x for x in d.rounds}
hv = r["99341", "PETM225D"]
assert (
hv.rule_year,
hv.proposed_work_rvu,
hv.final_work_rvu,
hv.ruc_percentile,
hv.decision,
) == (2023, 1.0, 1.0, "25th", "accept")
assert hv.rationale.url.endswith("#p-1685")
old = r["99343", "54GTKR5G"]
assert (
old.rule_year,
old.source,
old.ruc_work_rvu,
old.final_work_rvu,
old.decision,
old.page,
) == (2008, "fr-table", 2.27, 2.53, "refine", 66361)
assert r["99341", "MZ24MX5S"].rationale is None
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)
from pfs.utilization import SeriesRow
d2 = dataclasses.replace(
d, utilization=[SeriesRow("99341", 2023, 1, 2, 3.0, 4.0, 5.0)]
)
assert Dossier.from_json(d2.to_json()) == d2
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-recommended total time for 99342 was 97 minutes." in texts
)
assert (
"For CY2020, the RUC-recommended 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 earliest CPT edition on file (2021), 99341 has low medical decision making and add-on status."
in texts
)
assert (
"In the earliest CPT edition on file (2021), 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,
"The CPT Editorial Panel deleted the Domiciliary code family.",
"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 == "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",
"https://www.ssa.gov/OP_Home/ssact/title18/1834.htm",
locator="section 1834(m) of the Act",
)
def test_origin_iom_cite_carries_manual_url(home_fixture):
from bib.item import Manual
con, store, family, _ask = home_fixture
key = store.create(
Manual(
title="Medicare Claims Processing Manual \u2014 Chapter 12: Physicians",
url="https://www.cms.gov/x/clm104c12.pdf",
)
)
store.add_tag(key, "pub:100-04")
write_origin(
con,
family.key,
[
OriginRow(
family.key,
"99341",
"coverage",
"100-04 ch.12",
2019,
"CMS guidance for 99341 points to 100-04 ch.12.",
"iom",
"PETM225D",
1684,
"",
"100-04 ch.12",
"guidance",
),
OriginRow(
family.key,
"99341",
"coverage",
"100-04 ch.5",
2019,
"CMS guidance for 99341 points to 100-04 ch.5.",
"iom",
"PETM225D",
1684,
"",
"100-04 ch.5",
"guidance",
),
],
)
facts = collect_facts(con, store, family)
hit = next(f for f in facts if f.text.endswith("points to 100-04 ch.12."))
assert hit.cite.kind == "iom"
assert hit.cite.url == "https://www.cms.gov/x/clm104c12.pdf"
miss = next(f for f in facts if f.text.endswith("points to 100-04 ch.5."))
assert miss.cite.url == ""
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 _cms(fid, year, quote, codes=(), links=""):
return Fact(
fid,
"cms_summary",
year,
tuple(codes),
f'In the CY{year} final rule, CMS summarized: "{quote}"',
{"comment_first_sentence": quote, "link_codes": links},
Cite("fr_para", "l", "u"),
)
def test_timeline_routes_cms_summaries_by_what_the_comment_is_about():
facts = [
_cms("F1", 2005, "One commenter asked about house calls.", ("99341",)),
_f(
"F2",
"round",
2010,
"For CY2010, CMS finalized a work RVU of 1.00 for 99341.",
("99341",),
),
_cms("F3", 2010, "Commenters said the RVUs were too low.", ("99350",)),
_cms(
"F4",
2010,
"Commenters asked about place of service 12 for 99341.",
("99341",),
),
_f(
"F5",
"link",
2023,
"From CY2023, G0318 can be reported with this family (prolonged-add-on).",
("G0318",),
link_kind="prolonged-add-on",
),
_cms("F6", 2023, "A few commenters asked about GXXX3.", (), "G0318"),
_f(
"F7",
"event",
2023,
"99341 is named in a telehealth-list paragraph of the CY2023 rule.",
("99341",),
event_kind="telehealth_list",
),
_cms(
"F8",
2023,
"Commenters supported adding the codes to the telehealth list.",
("99341",),
),
_f(
"F9",
"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.startswith(
'In the CY2005 final rule, CMS summarized: "One commenter'
)
assert by[(2010, "valuation")].cms_summary_fact_ids == ("F3",)
# not about the valuation: its own comments event, never filed under it
assert by[(2010, "comments")].cms_summary_fact_ids == ("F4",)
assert by[(2023, "link:G0318")].cms_summary_fact_ids == ("F6",)
assert by[(2023, "telehealth_list")].cms_summary_fact_ids == ("F8",)
line = by[(2011, "comments")].what_changed
assert line.startswith("Of 2 CY2011 commenters") and line.endswith(
"Preliminary [F9]."
)
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 = _eligible(timeline(facts))[:1]
lead = next(f for f in facts if f.id == events[0].fact_ids[0])
three = " ".join(f"{lead.text.rstrip('.')} [{lead.id}]." for _ in range(3))
ask = FakeAsk(default={"text": three})
summary, lines, extractor, ok = write_prose(facts, events, ask)
assert extractor == "template"
assert "too long: 3 sentences, at most 2" in ask.calls[1][1]
def test_in_sample_line():
assert dos._in_sample_line({"recall": 0.5}) == ""
ev = {
"in_sample_record": {
"recall": 0.407,
"direction": 0.818,
"n_items": 20,
"n_positions": 27,
"docket": "CMS-2022-0113",
}
}
line = dos._in_sample_line(ev)
assert line == (
" Tuning-set record on CMS-2022-0113 (20 hand-coded comments, 27 "
"positions): it finds 41% of hand-coded positions, and the direction is "
"right for 82% of those it finds."
)
assert dos._in_sample_line(ev, "CMS-2022-0113") == line
assert dos._in_sample_line(ev, "CMS-2025-0304") == ""
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 = _eligible(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 == [f"CY{e.year} {e.kind}" for e in events]
d = build_dossier(con, store, family)
assert len(d.fallbacks) == len(_eligible(d.timeline))
assert "summary" not in d.fallbacks # template by rule, not a fallback
# ── fix round 1: R94 family filter, R96 link end, deletion cites ─────
from pfs.codetables import CmsSummaryRow, write_cms_summaries # noqa: E402
def test_cms_summaries_must_be_about_the_family(home_fixture):
con, store, family, _ask = home_fixture
paras = {
99101: "Comment: Commenters disagreed that CPT codes 99091 and 99457 can be billed together.",
99102: "Response: The codebook lists 99339 and 99340 among others.",
99103: "Comment: Commenters asked us to revisit travel costs.",
99104: "Response: The home visit codes 99347 and 99348 reflect travel. More.",
99105: "Comment: Commenters thanked us.",
99106: "Response: We appreciate the support.",
99107: "Comment: Commenters supported the e-prescribing measure. They noted domiciliary care visit codes.",
99108: "Response: We appreciate the support. The codes include 99324.",
99109: "Comment: Commenters asked about home or residence services.",
}
for p_id, text in paras.items():
_add_paragraph(store, p_id, text)
rows = [
CmsSummaryRow(
family.key,
"PETM225D",
2023,
"final",
c,
r,
"",
"unspecified",
"support",
"unclear",
"regex",
)
for c, r in (
(99101, 99102),
(99103, 99104),
(99105, 99106),
(99107, 99108),
(99109, 99999),
)
]
write_cms_summaries(con, family.key, rows)
cms = [f for f in collect_facts(con, store, family) if f.kind == "cms_summary"]
# about other codes (the family only listed in the response): dropped;
# nothing about the family: dropped; the family only in a later sentence:
# dropped; no code in the Comment and the Response opening with the
# family: kept; the Comment's first sentence naming the family: kept
assert sorted((f.cite.p_id, f.codes) for f in cms) == [
(99103, ("99347", "99348")),
(99109, ()),
]
assert any(
'CMS summarized: "Commenters asked us to revisit travel costs."' in f.text
for f in cms
)
def test_link_end_status_payment_and_summary(home_fixture):
con, store, family, _ask = home_fixture
d = build_dossier(con, store, family)
end = next(f for f in d.facts.values() if f.values.get("link_end") == "G2211")
assert end.text == "From CY2027, G2211 is replaced by modifiers B1 and B2."
assert (end.cite.item_key, end.cite.p_id) == ("JCWARTJD", 6666)
# ¶1194 ("we proposed …, which if finalized would be replaced") is a
# proposal, never the finalization (N1)
assert [(c.item_key, c.p_id) for c in end.also] == [("JCWARTJD", 3526)]
assert "G2211 CY2026 only; replaced by modifiers B1/B2 from CY2027" in d.status
assert any(e.kind == "link:G2211" and e.year == 2027 for e in d.timeline)
# the summary spans the earliest finalized valuation to the newest link,
# each statement once
sents = dos.split_sentences(d.summary)
assert len(sents) <= 5
assert sents[0].startswith("For CY2008, CMS finalized work RVUs")
assert "G2211 (from CY2026)" in sents[-1] and "B2 (from CY2027)" in sents[-1]
assert "from CY2027, G2211 is replaced by modifiers B1 and B2" in sents[-1]
assert sum("deleted" in s for s in sents) == 1
ids = d.facts
assert (
check_prose(d.summary, ids) == []
and dos.grounding_problems(d.summary, ids) == []
)
def test_payment_stops_at_a_link_end(home_fixture):
con, _store, family, _ask = home_fixture
rows = dos._payment_rows(con, family, {"99341": 2027})
assert rows and max(r.year for r in rows if r.code == "99341") == 2026
def test_link_end_edges(home_fixture):
con, store, family, _ask = home_fixture
from pfs.curated import CuratedLink
_add_paragraph(
store, 99201, "We are finalizing our proposal to replace code G9001."
)
_add_paragraph(store, 99202, "We proposed to replace code G9002 with G9003.")
_add_paragraph(
store,
99203,
"We are finalizing a policy to replace code G9004 with code G9005.",
)
fam = dataclasses.replace(
family,
links=(
CuratedLink("add-on", "G9000", None, None, "", 0, 0, 0),
CuratedLink("add-on", "G9001", 2020, None, "", 0, 0, 2020),
CuratedLink("add-on", "G9002", 2020, None, "", 0, 0, 2020),
CuratedLink("add-on", "G9004", 2023, None, "", 0, 0, 2023),
CuratedLink("add-on", "G9006", 2019, None, "", 0, 0, 2019),
CuratedLink("add-on", "G9005", 2023, None, "", 0, 0, 2023),
),
)
ends = dos._link_ends(dos._Bib(store), fam)
# G9001 has no successor named; G9002's sentence is a proposal; G9004's
# rule year is not after its since
assert [f.text for f in ends] == ["From CY2023, G9001 is replaced."]
assert dos._status(fam, ends).endswith(
"G9001 CY2020–CY2022; replaced from CY2023, G9002 from CY2020, G9004 from CY2023, G9006 from CY2019, G9005 from CY2023"
)
fam2 = dataclasses.replace(
family,
links=(
CuratedLink("add-on", "G9004", 2022, None, "", 0, 0, 2022),
CuratedLink("add-on", "G9005", 2023, None, "", 0, 0, 2023),
),
)
[e] = dos._link_ends(dos._Bib(store), fam2)
assert e.text == "From CY2023, G9004 is replaced by codes G9005."
assert dos._status(fam2, [e]).endswith(
"G9004 CY2022 only; replaced by codes G9005 from CY2023, G9005 from CY2023"
)
def test_deletions_cite_the_coding_paragraph(home_fixture):
con, store, family, _ask = home_fixture
facts = collect_facts(con, store, family)
for code in ("99324", "99328", "99343"):
f = next(f for f in facts if f.text == f"{code} was deleted for CY2023.")
assert (f.cite.item_key, f.cite.p_id) == ("PETM225D", 1672)
# 99339 has no curated paragraph: the paragraph that states it
f = next(f for f in facts if f.text == "99339 was deleted for CY2023.")
assert (f.cite.item_key, f.cite.p_id) == ("PETM225D", 390)
def test_edition_change_without_a_coding_paragraph(home_fixture):
con, store, family, _ask = home_fixture
write_guideline_facts(
con,
family.key,
[
GuidelineFactRow(
family.key, "99339", 2022, "mdm_level", "low", "K22", "p. 5", "cpt-book"
),
GuidelineFactRow(
family.key,
"99339",
2024,
"mdm_level",
"high",
"K24",
"p. 6",
"cpt-book",
),
GuidelineFactRow(
family.key,
"99343",
2023,
"deleted_in_edition",
"2022",
"CH23",
"p. 48",
"cpt-book",
),
],
)
facts = collect_facts(con, store, family)
f = next(f for f in facts if f.text.startswith("From the CY2023 code set, 99339"))
assert f.cite.label == "CPT Changes 2023 p. 48"
assert [c.label for c in f.also] == ["CPT 2024 p. 6"]
def test_nested_descriptor_is_stripped_once():
assert dos.strip_descriptors(
"99341 ( Home visit, see 99342 ( Nested words)) end"
) == ("99341 [CPT descriptor omitted] end")
def test_empty_model_answer_is_a_problem(home_fixture):
con, store, family, _ask = home_fixture
facts = collect_facts(con, store, family)
events = _eligible(timeline(facts))[:1]
ask = FakeAsk(default={"text": " "})
write_prose(facts, events, ask)
assert "empty: no text" in ask.calls[1][1]
def test_template_summary_without_valuations_or_links():
facts = [_cms("F1", 2005, "One commenter asked about house calls.", ("99341",))]
events = timeline(facts)
assert template_summary(facts, events).startswith(
'In the CY2005 final rule, CMS summarized: "One commenter'
)
def test_a_quote_keeps_its_closing_mark_and_every_sentence_is_tagged():
line = dos._with_tags(
'CMS summarized: "Codes were not valued." CMS said more.', ["F1"]
)
assert line == 'CMS summarized: "Codes were not valued." [F1] CMS said more [F1].'
assert dos.split_sentences(line) == [
'CMS summarized: "Codes were not valued." [F1]',
"CMS said more [F1].",
]
facts = {
"F1": _f(
"F1",
"cms_summary",
2005,
'CMS summarized: "Codes were not valued." CMS said more.',
)
}
assert check_prose(line, facts) == [] and dos.grounding_problems(line, facts) == []
def test_a_stray_full_stop_stays_with_its_sentence():
assert dos.split_sentences('He said "x." [F1]. Next [F2].') == [
'He said "x." [F1].',
"Next [F2].",
]
# ── fix round 2: N1, R97, the CY2023 edition line ────────────────────
def test_an_if_finalized_sentence_ends_no_link(home_fixture):
con, store, family, _ask = home_fixture
from pfs.curated import CuratedLink
_add_paragraph(
store,
99301,
"Code G9001, which if finalized would be replaced with code G9005, stays.",
)
_add_paragraph(
store, 99302, "If this is finalized, we will replace code G9002 with G9005."
)
fam = dataclasses.replace(
family,
links=(
CuratedLink("add-on", "G9001", 2020, None, "", 0, 0, 2020),
CuratedLink("add-on", "G9002", 2020, None, "", 0, 0, 2020),
CuratedLink("add-on", "G9005", 2023, None, "", 0, 0, 2023),
),
)
assert dos._link_ends(dos._Bib(store), fam) == []
def test_link_and_edition_lines_are_template_copy(home_fixture):
con, store, family, _ask = home_fixture
facts = collect_facts(con, store, family)
events = timeline(facts)
ids = {f.id: f for f in facts}
ask = FakeAsk(default=_echo)
_summary, lines, _extractor, _ok = write_prose(facts, events, ask)
for i, e in enumerate(events):
if e.kind.startswith("link:") or e.kind == "cpt_edition":
assert lines[i] == template_event_line(e, ids)
assert not [u for _s, u in ask.calls if "Event: CY2027, link:" in u]
edition = next(e for e in events if e.kind == "cpt_edition" and e.year == 2023)
assert lines[events.index(edition)] == (
"From the CY2023 code set, 99341 and 99350 are selected on medical decision "
f"making or total time (CPT 2024 codebook) {dos._tags(edition.fact_ids)}."
)
def test_cms_summaries_held_for_review(home_fixture):
con, store, family, _ask = home_fixture
paras = {
99401: "Comment: Commenters asked us to revisit travel costs.",
99402: "Response: We appreciate the comments. The home visit codes 99347 and 99348 reflect travel.",
99403: "Comment: Commenters asked about codes 99091 and 99457 in long lists.",
99404: "Response: We note 99339 among many codes.",
}
for p_id, text in paras.items():
_add_paragraph(store, p_id, text)
write_cms_summaries(
con,
family.key,
[
CmsSummaryRow(
family.key,
"PETM225D",
2023,
"final",
c,
r,
"",
"unspecified",
"support",
"unclear",
"regex",
)
for c, r in ((99401, 99402), (99403, 99404))
],
)
d = build_dossier(con, store, family)
held = [r for r in d.review if r.get("kind") == "cms_summary"]
# the family only later in CMS's Response: held; other codes: not
assert [(r["cite"]["p_id"], r["response"]["p_id"]) for r in held] == [
(99401, 99402)
]
assert held[0]["quote"] == "Commenters asked us to revisit travel costs."
assert not [f for f in d.facts.values() if f.kind == "cms_summary"]
assert "1 CMS comment summary held for review." in d.gaps
_add_paragraph(store, 99405, "Comment: Commenters asked about travel.")
_add_paragraph(
store, 99406, "Response: Thanks. Domiciliary care visit codes apply."
)
write_cms_summaries(
con,
family.key,
[
CmsSummaryRow(
family.key,
"PETM225D",
2023,
"final",
c,
r,
"",
"unspecified",
"support",
"unclear",
"regex",
)
for c, r in ((99401, 99402), (99405, 99406))
],
)
assert "2 CMS comment summaries held for review." in coverage(con, store, family)
def test_edition_line_keeps_a_fact_without_a_basis_and_a_single_code():
head = "In the earliest CPT edition on file (2021)"
facts = [
_f(
"F1",
"event",
2021,
f"{head}, 99341 has low medical decision making.",
("99341",),
event_kind="cpt_edition",
edition=2021,
head=head,
basis="",
),
_f(
"F2",
"event",
2021,
f"{head}, 99350 is selected on other basis.",
("99350",),
event_kind="cpt_edition",
edition=2021,
head=head,
basis="is selected on other basis",
),
]
[e] = timeline(facts)
assert e.what_changed == (
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 in the CY2024 RVU file (status A)",
"lineage contradiction: 99418 is in the CY2025 RVU file (status A)",
"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",
)
# ── readiness 7: a layer never run says so, from its row counts ──────
def test_layers_never_extracted_are_stated(home_fixture):
from pfs.curated import CuratedFamily, CuratedMember
con, store, family, _ask = home_fixture
fam = CuratedFamily(
"PROLONGED",
"Prolonged Services",
(),
(CuratedMember("99418", "member", None, None, "", 0, 0, 0),),
(),
)
gaps = coverage(con, store, fam)
assert (
"Not yet extracted for this family: lineage events, valuation rounds, "
"origin and formation, CPT guideline facts, CMS comment summaries, "
"commenters, comment stance, PSPS billing by specialty, Medicare "
"utilization." in gaps
)
home = coverage(con, store, family)
assert [g for g in home if g.startswith("Not yet extracted")] == [
"Not yet extracted for this family: Medicare utilization."
]
def test_a_code_still_listed_later_was_not_deleted(home_fixture):
"""I8a: Medicare lists 99418 with status I (not paid) from CY2023 on; a
code still in a later RVU file was not deleted, so its creation stands."""
con, store, _family, _ask = home_fixture
fam = _prolonged(con, store)
con.execute("UPDATE pfs.rvu SET status_code = 'I' WHERE hcpcs = '99418'")
a = dos._assemble(con, store, fam)
events = {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 "lineage contradiction: 99418 is in the CY2024 RVU file (status I)" in {
r["reason"] for r in a.review
}
def test_lineage_pass_edges(home_fixture, monkeypatch, caplog):
con, store, family, _ask = home_fixture
# no codes, no RVU table: nothing to judge by
assert dos._rvu_years(con, []) == ({}, {}, None)
bare = duckdb.connect(":memory:")
assert dos._rvu_years(bare, ["99341"]) == ({}, {}, None)
class _Broken:
def execute(self, *a, **k):
raise RuntimeError("boom")
with pytest.raises(RuntimeError):
dos._rvu_years(_Broken(), ["99341"])
# an event from neither the FR nor the RVU file states nothing
write_events(
con,
"99341",
[EventRow("99341", 2023, "created", "", "", "", 0, 0, "cpt", True, "")],
)
assert "99341 was created for CY2023." not in _texts(
collect_facts(con, store, family), "event"
)
# an unreadable licensed book is no check, never an error
import pfs.guideline_facts as gf
monkeypatch.setattr(gf, "load_pages", lambda s, k: 1 / 0)
with caplog.at_level("WARNING", logger="pfs.dossier"):
assert dos._Bib(store).book_page("BOOK", "49") == ""
assert "book BOOK unreadable" in caplog.text