fix(pfs): dossier facts made honest — lineage contradictions dropped (I8a), model origin rows flagged and grounded, statutes final-only (I3), link codes windowed by since (I2), merger money states its coverage and the unpriced move (I1), stakeholder labels marked model readings (I4), stance under the family's own events (M1), accuracy names its event kinds and each docket's method (M2, M3), per-year RVU and Addendum B cites (M4), the book page cites the minutes (M6)

This commit is contained in:
kert
2026-11-13 03:22:09 -05:00
parent 7a5f6df115
commit 929b5ff605
9 changed files with 1020 additions and 97 deletions

View File

@@ -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:

View File

@@ -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:

View File

@@ -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,

View File

@@ -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

View File

@@ -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"``."""

View File

@@ -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"]

View File

@@ -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) == (

View File

@@ -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",
)

View File

@@ -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),
]