feat(pfs): CPT guideline facts from the licensed books (R69), stance-v5 coding event from facts, link relevance by kind, home-and-residence pair phrases (R74)

pfs guideline-facts writes pfs.code_guideline_fact: selection basis, MDM level,
time thresholds, deletions between editions, copy-guarded scope points and the
Feb 2021 Panel action, each cited by (edition, page). stance-v5 states the CPT
change in the coding event and drops keyword-only coding events; v5 ships on
the golden set (recall 14/27, direction 11/14 vs v4 13/27, 10/13).
This commit is contained in:
kert
2026-11-12 17:19:09 -05:00
parent 6c4587d0be
commit 71227e879d
10 changed files with 2128 additions and 39 deletions

View File

@@ -53,6 +53,7 @@ from pfs.codetables import (
write_exposures,
write_families,
write_guidance,
write_guideline_facts,
write_origin,
write_reaction,
write_rounds,
@@ -74,23 +75,27 @@ from pfs.families import (
refresh_from,
)
from pfs.guidance import build as build_guidance
from pfs.guideline_facts import guideline_facts
from pfs.lineage import lineage, lineage_all, seen_codes
from pfs.origin import DEFAULT_BOOK, family_origin, origin_inventory, resolve_book
from pfs.reaction import series as reaction_series
from pfs.rounds import family_rounds, rounds_inventory
from pfs.runlog import RunLog, ledger_path
from pfs.stance import (
DEFAULT_GENERATION,
DEFAULT_METHOD,
DEFAULT_MODEL,
GENERATIONS,
GOLDEN_PATH,
METHODS,
PROMPT_VERSIONS,
TEXT_CHARS,
TEXT_CHUNKS,
docket_events,
docket_rule_year,
eval_record,
event_subjects,
guideline_text,
prompt_version,
rollup,
score,
stances_for,
@@ -1278,6 +1283,67 @@ def origin(
_publish()
@app.command("guideline-facts")
def guideline_facts_cmd(
family: str = typer.Option(..., "--family", help="Curated family key."),
limit: int = typer.Option(0, "--limit", help="Cap new model calls (0 = all)."),
no_llm: bool = typer.Option(
False, "--no-llm", help="Make no model calls; the finished ledger is replayed."
),
retry_failed: bool = typer.Option(
False, "--retry-failed", help="Re-run ledger entries that failed."
),
write: bool = typer.Option(False, "--write"),
) -> None:
"""Guideline facts from the licensed CPT books (pfs.code_guideline_fact):
selection basis, MDM level, time threshold, add-on and deletion per code
and edition, scope points and the Panel action as paraphrases, each cited
by (edition, page). Book text is never stored."""
fam = curated_family(normalize_key(family))
if fam is None:
raise typer.BadParameter(f"unknown curated family {family!r}")
store = _store()
ask = None
if not no_llm:
try:
ask = _asker()
except RuntimeError as exc:
typer.echo(f"no model host available ({exc}); replaying the ledger")
counts: dict[str, int] = {}
con = _read()
try:
rows = guideline_facts(
con,
store,
fam,
ask=ask,
log=RunLog(ledger_path("guideline", fam.key)),
limit=limit,
retry_failed=retry_failed,
replay_model=_model_name() if ask is None else None,
counts=counts,
)
finally:
con.close()
tally: dict[tuple[int, str], int] = {}
for r in rows:
tally[(r.edition_year, r.fact)] = tally.get((r.edition_year, r.fact), 0) + 1
for (year, fact), n in sorted(tally.items()):
typer.echo(f"{year} {fact}: {n}")
typer.echo(
f"facts: {len(rows)}; done {counts.get('done', 0)}, skipped "
f"{counts.get('skipped', 0)}, failed {counts.get('failed', 0)}, "
f"failed_pending {counts.get('failed_pending', 0)}, "
f"cited by section (no page) {counts.get('unpaged', 0)}"
)
if write:
with _batch() as bcon:
ensure_tables(bcon)
n = write_guideline_facts(bcon, fam.key, rows)
typer.echo(f"wrote {n} facts")
_publish()
@app.command("cms-summaries")
def cms_summaries(
family: str = typer.Option(..., "--family", help="Curated family key."),
@@ -1427,6 +1493,11 @@ def stance(
"--golden",
help="Golden set whose measurement --write records (its family only).",
),
generation: str = typer.Option(
DEFAULT_GENERATION,
"--generation",
help="Prompt generation: stance-v4 or stance-v5 (CPT guideline facts).",
),
write: bool = typer.Option(False, "--write"),
) -> None:
"""Each commenter's stance (support / modify / oppose / unclear) on each
@@ -1437,6 +1508,10 @@ def stance(
raise typer.BadParameter(f"--method must be one of {', '.join(METHODS)}")
if model not in ("instruct", "large"):
raise typer.BadParameter("--model must be instruct or large")
if generation not in GENERATIONS:
raise typer.BadParameter(
f"--generation must be one of {', '.join(GENERATIONS)}"
)
fam = curated_family(normalize_key(family))
if fam is None:
raise typer.BadParameter(f"unknown curated family {family!r}")
@@ -1447,7 +1522,9 @@ def stance(
year = docket_rule_year(found[0].comment_end_date)
con = _read()
try:
events = docket_events(con, fam, year, store)
events = docket_events(
con, fam, year, store, guidelines=guideline_text(generation)
)
commenter_rows = [
c for c in read_commenters(con, family=fam.key) if c.docket == docket
]
@@ -1494,8 +1571,9 @@ def stance(
family=fam.key,
docket=docket,
method=method,
generation=generation,
model=name if no_llm else None,
subjects=event_subjects(fam, events),
subjects=event_subjects(fam, events, by_kind=guideline_text(generation)),
limit=limit,
retry_failed=retry_failed,
progress=lambda unit, status: typer.echo(f"{unit} {status}"),
@@ -1531,9 +1609,9 @@ def stance(
)
new = replace(
rollup(rows, base=base, order=order, n_commenters=len(commenter_rows)),
stance_method=f"{PROMPT_VERSIONS[method]}:{name}",
stance_method=f"{prompt_version(method, generation)}:{name}",
stance_agreement=None,
stance_eval=_method_eval(golden, method, name, fam.key),
stance_eval=_method_eval(golden, method, name, fam.key, generation),
)
keep = [
r
@@ -1548,7 +1626,9 @@ def stance(
_publish()
def _method_eval(golden: Path, method: str, name: str, family: str) -> str | None:
def _method_eval(
golden: Path, method: str, name: str, family: str, generation: str | None = None
) -> str | None:
"""The method's measurement on the golden set as ``stance_eval`` JSON
(R66a), replayed from the ledger (no model call). ``None`` when there is
no golden file, the golden set is another family's, or its ledger is
@@ -1558,7 +1638,7 @@ def _method_eval(golden: Path, method: str, name: str, family: str) -> str | Non
data = json.loads(golden.read_text(encoding="utf-8"))
if data.get("family") != family:
return None
sc, _ = _golden_run(data, method, ask=None, name=name)
sc, _ = _golden_run(data, method, ask=None, name=name, generation=generation)
if sc is None:
typer.echo(f"golden set not fully classified for {method} on {name}")
return None
@@ -1571,6 +1651,7 @@ def _golden_run(
*,
ask: Any,
name: str,
generation: str | None = None,
relevance: bool = True,
limit: int = 0,
retry_failed: bool = False,
@@ -1590,7 +1671,11 @@ def _golden_run(
con = _read()
try:
events = docket_events(
con, fam, docket_rule_year(found[0].comment_end_date), store
con,
fam,
docket_rule_year(found[0].comment_end_date),
store,
guidelines=guideline_text(generation),
)
finally:
con.close()
@@ -1617,8 +1702,13 @@ def _golden_run(
family=fam.key,
docket=docket,
method=method,
generation=generation,
model=name if ask is None else None,
subjects=event_subjects(fam, events) if relevance else None,
subjects=(
event_subjects(fam, events, by_kind=guideline_text(generation))
if relevance
else None
),
limit=limit,
retry_failed=retry_failed,
progress=progress,
@@ -1640,6 +1730,9 @@ def stance_eval(
no_relevance: bool = typer.Option(
False, "--no-relevance", help="Skip the event-subject filter (R65)."
),
generation: str = typer.Option(
DEFAULT_GENERATION, "--generation", help="stance-v4 or stance-v5."
),
) -> None:
"""Score a stance method against a hand-coded golden set: cell agreement,
presence agreement, firm-stance accuracy and a confusion matrix. The
@@ -1652,6 +1745,10 @@ def stance_eval(
raise typer.BadParameter(f"--method must be one of {', '.join(METHODS)}")
if model not in ("instruct", "large"):
raise typer.BadParameter("--model must be instruct or large")
if generation not in GENERATIONS:
raise typer.BadParameter(
f"--generation must be one of {', '.join(GENERATIONS)}"
)
data = json.loads(golden.read_text(encoding="utf-8"))
large = model == "large"
ask = None if no_llm else _asker(large=large)
@@ -1662,6 +1759,7 @@ def stance_eval(
method,
ask=ask,
name=name,
generation=generation,
relevance=not no_relevance,
limit=limit,
retry_failed=retry_failed,
@@ -1669,7 +1767,8 @@ def stance_eval(
)
calls = counts["done"] + counts["failed"]
typer.echo(
f"{method} on {name}{' (no relevance filter)' if no_relevance else ''}: "
f"{prompt_version(method, generation)} {method} on {name}"
f"{' (no relevance filter)' if no_relevance else ''}: "
f"{calls} new calls in {time.monotonic() - began:.0f}s; done {counts['done']}, "
f"skipped {counts['skipped']}, failed {counts['failed']}, failed_pending "
f"{counts['failed_pending']}, pending {counts['pending']}, "

View File

@@ -464,8 +464,45 @@ class OriginRow:
ref_p_id: int = 0
GUIDELINE_FACTS = (
"selection_basis",
"mdm_level",
"time_threshold_min",
"typical_time_min",
"addon",
"scope_point",
"deleted_in_edition",
"panel_action",
)
@dataclass(frozen=True)
class GuidelineFactRow:
"""One fact the licensed CPT books state about a family code
(``pfs.code_guideline_fact``). ``value`` is structured (a basis, an MDM
level, minutes as an integer string, an edition year) or, for
``scope_point`` and ``panel_action``, a paraphrase of at most 240
characters; never book text. ``cite_item`` is the bib item of the book
(or the Panel summary), ``cite_locator`` its printed page ("p. 28",
"tab 10, p. 4"), or the section path where the edition carries no page
markers (R72). For ``scope_point``/``panel_action`` rows ``code`` is the
code range the passage covers ("99341-99350")."""
family: str
code: str
edition_year: int
fact: str
value: str
cite_item: str
cite_locator: str
extractor: str
_DDL = """
CREATE SCHEMA IF NOT EXISTS pfs;
CREATE TABLE IF NOT EXISTS pfs.code_guideline_fact (
family VARCHAR, code VARCHAR, edition_year INTEGER, fact VARCHAR,
value VARCHAR, cite_item VARCHAR, cite_locator VARCHAR, extractor VARCHAR);
CREATE TABLE IF NOT EXISTS pfs.code_element (
code VARCHAR, year INTEGER, type VARCHAR, value VARCHAR, detail VARCHAR,
text VARCHAR, item_key VARCHAR, p_id INTEGER, page INTEGER, source VARCHAR,
@@ -996,6 +1033,23 @@ def read_origin(con: Any, family: str) -> list[OriginRow]:
return [OriginRow(*r[:-1], r[-1] or 0) for r in rows]
def write_guideline_facts(
con: Any, family: str, rows: Sequence[GuidelineFactRow]
) -> int:
ensure_tables(con)
con.execute("DELETE FROM pfs.code_guideline_fact WHERE family = ?", [family])
return _insert(con, "pfs.code_guideline_fact", rows)
def read_guideline_facts(con: Any, family: str) -> list[GuidelineFactRow]:
rows = con.execute(
"SELECT * FROM pfs.code_guideline_fact WHERE family = ? "
"ORDER BY edition_year, code, fact, cite_locator, value",
[family],
).fetchall()
return [GuidelineFactRow(*r) for r in rows]
def write_cms_summaries(con: Any, family: str, rows: Sequence[CmsSummaryRow]) -> int:
ensure_tables(con)
con.execute("DELETE FROM pfs.cms_comment_summary WHERE family = ?", [family])

View File

@@ -5,7 +5,7 @@ HOME-VISITS:
synonyms: [home visit, home visits, home or residence, residence visit, domiciliary, rest home visit, house call, house calls]
# Phrases that qualify a Comment:/Response: pair besides a code (pfs.cms_summaries).
# Visit-naming only; each was checked against every phrase-only row it admits.
pair_phrases: [home or residence visit, home or residence services, home or residence e/m, residence visit, rest home visit, home visit codes, home visit e/m, house call, domiciliary care visit, visit in the home, home residence e/m, domiciliary care setting, domiciliary care settings, home visit pes, home or residence setting]
pair_phrases: [home or residence visit, home or residence services, home or residence e/m, residence visit, rest home visit, home visit codes, home visit e/m, house call, domiciliary care visit, visit in the home, home residence e/m, domiciliary care setting, domiciliary care settings, home visit pes, home or residence setting, home and residence e/m, home and residence]
members:
- {code: '99341', role: base, cite: {item_key: PETM225D, p_id: 1672}}
- {code: '99342', role: base, cite: {item_key: PETM225D, p_id: 1672}}

606
src/pfs/guideline_facts.py Normal file
View File

@@ -0,0 +1,606 @@
"""Guideline facts about a family's codes from the licensed CPT books
(``pfs.code_guideline_fact``, task 9b, R69).
Three layers, every row citing (edition, printed page):
* deterministic facts read off ``pfs.cpt_code`` (selection basis, MDM level,
total-time threshold or typical time, add-on) and the edition-to-edition
deletion of a code; values only, never descriptor prose;
* up to six scope-point paraphrases per edition, from the guideline text of
the subsection(s) that hold the family's codes, asked of the pinned local
model through the resumable ledger;
* the public CPT Editorial Panel summary entry for the revision, one
paraphrase with its tab and page.
A paraphrase is kept only if it is at most 240 characters, shares no run of
eight words with its source (:func:`pfs.origin.shares_run`) and carries no
number the source lacks; one that fails is dropped, never trimmed. The
ledger stores only kept paraphrases, never book text.
"""
from __future__ import annotations
import re
from collections.abc import Callable, Mapping, Sequence
from pathlib import Path
from typing import Any
from pfs.codetables import GuidelineFactRow, is_missing_table_error
from pfs.origin import resolve_book, shares_run
from pfs.runlog import RunLog, input_hash, ledger_path, run_units
GUIDELINE_PROMPT_VERSION = "guideline-v1"
PANEL_ITEM = "F7SRZJD2" # "February 2021: CPT Editorial Summary of Panel Actions"
PANEL_TITLES = ("Home and Residence Services",)
MAX_POINTS = 6
SUMMARY_CHARS = 240
BOOK_EXTRACTOR = "cpt-book"
SCHEMA: dict = {
"type": "object",
"required": ["points"],
"properties": {
"points": {
"type": "array",
"items": {
"type": "object",
"required": ["summary"],
"properties": {"summary": {"type": "string", "maxLength": 240}},
},
}
},
}
SYSTEM = (
"You read a passage of licensed coding-guideline text and state, in your own "
"words, what it says about where and for whom the listed codes are reported, "
"what counts toward their time, and any reporting rule it gives. Reply with "
'JSON {"points": [{"summary": ...}]}: at most four points, each one sentence '
"of at most 200 characters. Paraphrase: never copy eight or more consecutive "
"words of the passage, never quote, and never state a number the passage does "
"not contain. Say nothing the passage does not say, and never describe what "
"the passage lacks."
)
PANEL_SYSTEM = (
"You read one entry of a CPT Editorial Panel summary of actions and state in "
"your own words what the Panel did to the listed codes and subsections and "
'when it takes effect. Reply with JSON {"points": [{"summary": ...}]}: one '
"point of at most 200 characters. Paraphrase: never copy eight or more "
"consecutive words, never quote, never state a number the entry does not "
"contain."
)
_MARKS = re.compile("[▶◀■➢▲★●◆►◄▼\x00]")
_WS = re.compile(r"\s+")
_SENTENCE = re.compile(r"(?<=[.!?])\s+")
_NUMBER = re.compile(r"\d+")
#: a point about what the passage lacks says nothing
_VOID = re.compile(
r"^(?:no|none|nothing)\b|\bnot (?:given|specified|stated|provided)\b", re.I
)
_YEAR = re.compile(r"\b(20\d{2})\b")
_CODE5 = re.compile(r"(?<!\d)(\d{5})(?!\d)")
_BASIS_LABEL = {
"history_exam_mdm": "history, examination and medical decision making",
"mdm_or_time": "level of medical decision making or total time",
}
_LEVEL_A = re.compile(
r"\b(straightforward|(low|moderate|high) level of) medical decision making", re.I
)
_LEVEL_B = re.compile(
r"medical decision making of (low|moderate to high|moderate|high) complexity", re.I
)
_THRESHOLD = re.compile(r"(\d+) minutes must be met or exceeded", re.I)
_TYPICAL = re.compile(r"\btypically,? (\d+) minutes", re.I)
# ── values ───────────────────────────────────────────────────────────
def norm(text: str) -> str:
"""*text* without symbol markers, whitespace collapsed."""
return _WS.sub(" ", _MARKS.sub("", text)).strip()
def selection_basis(descriptor: str, elements: Sequence[str]) -> str | None:
"""``history_exam_mdm`` (key components) or ``mdm_or_time`` (a medically
appropriate history/exam and MDM or total time)."""
low = descriptor.lower()
if elements or "key components" in low:
return "history_exam_mdm"
if "medically appropriate history" in low:
return "mdm_or_time"
return None
def mdm_level(descriptor: str) -> str | None:
if m := _LEVEL_A.search(descriptor):
return (m.group(2) or m.group(1)).lower()
if m := _LEVEL_B.search(descriptor):
return m.group(1).lower().replace(" to ", "_to_")
return None
def time_facts(descriptor: str) -> dict[str, int]:
if m := _THRESHOLD.search(descriptor):
return {"time_threshold_min": int(m.group(1))}
if m := _TYPICAL.search(descriptor):
return {"typical_time_min": int(m.group(1))}
return {}
# ── pages ────────────────────────────────────────────────────────────
def find_page(
pages: Sequence[tuple[str, str]], snippet: str, start: int = 0
) -> int | None:
"""Index of the first labelled page at or after *start* whose text holds
*snippet* (markers and whitespace ignored)."""
want = norm(snippet)
for i in range(start, len(pages)):
label, text = pages[i]
if label and want in norm(text):
return i
return None
def code_index(
pages: Sequence[tuple[str, str]], code: str, descriptor: str
) -> int | None:
"""Index of the printed page where *code* is listed with its descriptor."""
return find_page(pages, f"{code} {norm(descriptor)[:30]}")
def code_page(
pages: Sequence[tuple[str, str]], code: str, descriptor: str
) -> str | None:
"""Printed page where *code* is listed with its descriptor."""
i = code_index(pages, code, descriptor)
return None if i is None else pages[i][0]
#: how many pages before a section's first listed code its guideline may start
_GUIDE_SPAN = 3
def sentence_page(
pages: Sequence[tuple[str, str]], snippet: str, near: int
) -> int | None:
"""Index of the page holding *snippet* closest before (or at) page
*near*, looking back ``_GUIDE_SPAN`` pages (a guideline sits just ahead of
the codes it governs; the same sentence also opens other subsections);
else the first page just after *near* that holds it."""
want = norm(snippet)
lo, hi = max(0, near - _GUIDE_SPAN), min(len(pages), near + 2)
hits = [i for i in range(lo, hi) if pages[i][0] and want in norm(pages[i][1])]
before = [i for i in hits if i <= near]
return max(before) if before else (hits[0] if hits else None)
def guarded_points(out: Any, text: str) -> list[str]:
"""The model's paraphrases that pass the guards: a string of 1..240
characters, no 8-word run shared with *text*, no number *text* lacks;
duplicates dropped."""
items = out.get("points") if isinstance(out, dict) else None
if not isinstance(items, list):
return []
have = set(_NUMBER.findall(text))
kept: list[str] = []
for it in items:
s = it.get("summary") if isinstance(it, dict) else None
if not isinstance(s, str):
continue
s = s.strip()
if (
s
and len(s) <= SUMMARY_CHARS
and not shares_run(s, text)
and set(_NUMBER.findall(s)) <= have
and not _VOID.search(s)
and s not in kept
):
kept.append(s)
return kept
def panel_entry(pages: Sequence[str], title: str) -> tuple[str, int, str] | None:
"""``(tab, page number, entry text)`` of the Panel-summary entry named
*title*: the tab number precedes the name, the entry runs to the next
tab's number and name."""
head = re.compile(rf"(?m)^(\d{{1,2}})[ \t]*\n[ \t]*{re.escape(title)}[ \t]*\n")
nxt = re.compile(r"(?m)^\d{1,2}[ \t]*\n[A-Z][a-z]")
for i, text in enumerate(pages):
if m := head.search(text):
body = text[m.end() :]
if n := nxt.search(body):
body = body[: n.start()]
return m.group(1), i + 1, norm(body)
return None
def load_pages(store: Any, item_key: str) -> list[tuple[str, str]] | None:
"""Printed pages ``(label, text)`` of the book's EPUB, or ``None``."""
from pfs.origin import book_pages # noqa: PLC0415
found = resolve_book(store, item_key)
return None if found is None else book_pages(found[1])
def load_panel(store: Any, item_key: str) -> list[str] | None:
"""Page texts of the Panel summary's PDF, or ``None``."""
con = store._con() # noqa: SLF001
for fn, sp in con.execute(
"SELECT a.filename, a.storage_path FROM attachments a "
"JOIN items i ON i.id = a.item_id WHERE i.key = ? ORDER BY a.id",
(item_key,),
).fetchall():
if str(fn).lower().endswith(".pdf") and sp and Path(sp).is_file():
import pymupdf # noqa: PLC0415 - the chat image has no PDFs
with pymupdf.open(sp) as doc:
return [p.get_text() for p in doc]
return None
# ── data ─────────────────────────────────────────────────────────────
def _rows(con: Any, sql: str, params: Sequence[Any] = ()) -> list[tuple]:
try:
return con.execute(sql, list(params)).fetchall()
except Exception as exc: # noqa: BLE001 - only a missing table is tolerated
if is_missing_table_error(exc):
return []
raise
def _cpt(con: Any, codes: Sequence[str]) -> list[dict]:
marks = ",".join("?" * len(codes))
rows = _rows(
con,
"SELECT c.edition_year, c.item_key, c.code, c.descriptor, c.elements, "
"c.addon, s.path FROM pfs.cpt_code c LEFT JOIN pfs.cpt_section s "
"ON s.edition_year = c.edition_year AND s.item_key = c.item_key "
f"AND s.sec_id = c.sec_id WHERE c.code IN ({marks}) "
"ORDER BY c.edition_year, c.code",
codes,
)
return [
{
"year": r[0],
"item": r[1],
"code": r[2],
"descriptor": r[3] or "",
"elements": list(r[4] or []),
"addon": bool(r[5]),
"path": tuple(r[6] or ()),
}
for r in rows
]
def _guidelines(con: Any, years: Sequence[int]) -> dict[tuple[int, tuple], str]:
marks = ",".join("?" * len(years))
return {
(r[0], tuple(r[1])): r[2]
for r in _rows(
con,
"SELECT edition_year, path, guideline FROM pfs.cpt_section "
f"WHERE edition_year IN ({marks}) AND guideline <> ''",
years,
)
}
def _range(codes: Sequence[str]) -> str:
lo, hi = min(codes), max(codes)
return lo if lo == hi else f"{lo}-{hi}"
def _where(path: tuple) -> str:
return " > ".join(path)
def _facts(
family: str, rows: list[dict], pages: Mapping[int, list], counts: dict[str, int]
) -> list[GuidelineFactRow]:
out: list[GuidelineFactRow] = []
def locate(r: dict) -> str:
label = code_page(pages[r["year"]], r["code"], r["descriptor"])
if label is not None:
return f"p. {label}"
counts["unpaged"] += 1
return _where(r["path"])
def add(r: dict, fact: str, value: str, locator: str) -> None:
out.append(
GuidelineFactRow(
family, r["code"], r["year"], fact, value, r["item"], locator,
BOOK_EXTRACTOR,
)
) # fmt: skip
for r in rows:
values = {
"selection_basis": selection_basis(r["descriptor"], r["elements"]),
"mdm_level": mdm_level(r["descriptor"]),
"addon": "true" if r["addon"] else None,
**{k: str(v) for k, v in time_facts(r["descriptor"]).items()},
}
stated = {k: v for k, v in values.items() if v is not None}
where = locate(r) if stated else ""
for fact, value in stated.items():
add(r, fact, value, where)
by_year: dict[int, dict[str, dict]] = {}
for r in rows:
by_year.setdefault(r["year"], {})[r["code"]] = r
years = sorted(by_year)
for prev, year in zip(years, years[1:], strict=False):
here = by_year[year]
anchor = here[sorted(here)[0]]
where = locate(anchor)
for code in sorted(set(by_year[prev]) - set(here)):
out.append(
GuidelineFactRow(
family, code, year, "deleted_in_edition", str(prev),
anchor["item"], where, BOOK_EXTRACTOR,
)
) # fmt: skip
return out
def _scope_jobs(
rows: list[dict],
guides: Mapping[tuple[int, tuple], str],
pages: Mapping[int, list],
counts: dict[str, int],
) -> list[dict]:
"""One job per (edition, subsection, printed page): the subsection's
guideline sentences that sit on that page."""
sections: dict[tuple[int, tuple], list[dict]] = {}
for r in rows:
for n in range(2, len(r["path"]) + 1):
key = (r["year"], r["path"][:n])
if guides.get(key):
sections.setdefault(key, []).append(r)
jobs = []
for (year, path), members in sorted(sections.items()):
guide = guides[(year, path)]
sents = _SENTENCE.split(norm(guide))
pgs = pages[year]
listed = [
i
for m in members
if (i := code_index(pgs, m["code"], m["descriptor"])) is not None
]
found: list[int | None] = [
sentence_page(pgs, s[:40], min(listed)) if listed else None for s in sents
]
known = [i for i in found if i is not None]
if known:
last = known[0]
for k, i in enumerate(found):
last = found[k] = last if i is None else i
else:
counts["unpaged"] += 1
codes = sorted({m["code"] for m in members})
groups: dict[int | None, list[str]] = {}
for s, i in zip(sents, found, strict=True):
groups.setdefault(i, []).append(s)
for i, group in groups.items():
label = None if i is None else pgs[i][0]
jobs.append(
{
"unit": f"scope:{year}:{_where(path)}:{label or '-'}",
"edition": year,
"item": members[0]["item"],
"code": _range(codes),
"text": " ".join(group),
"guide": norm(guide),
"system": SYSTEM,
"locator": f"p. {label}" if label else _where(path),
"user": (
f"CODES: {', '.join(codes)}\nSOURCE: CPT {year} guideline, "
f"{path[-1]}{f', page {label}' if label else ''}\n\n"
f"PASSAGE:\n{' '.join(group)}"
),
}
)
return jobs
def _panel_jobs(
store: Any, family_codes: Sequence[str], year_of: Callable[[str], int] | None = None
) -> list[dict]:
pages = load_panel(store, PANEL_ITEM) or []
jobs = []
for title in PANEL_TITLES:
found = panel_entry(pages, title)
if found is None:
continue
tab, page, text = found
named = sorted(set(_CODE5.findall(text)) & set(family_codes))
if not named:
continue
years = _YEAR.findall(text)
jobs.append(
{
"unit": f"panel:{PANEL_ITEM}:{tab}",
"edition": int(years[-1]) if years else 0,
"item": PANEL_ITEM,
"code": _range(named),
"text": text,
"guide": text,
"system": PANEL_SYSTEM,
"locator": f"tab {tab}, p. {page}",
"user": f"CODES: {', '.join(named)}\nSOURCE: Panel summary, tab {tab}\n\nENTRY:\n{text}",
}
)
return jobs
def _ask_job(ask: Callable, job: dict) -> dict | None:
out = ask(job["system"], job["user"], SCHEMA)
if out is None:
return None
return {"points": [{"summary": s} for s in guarded_points(out, job["guide"])]}
def _interleave(groups: list[list[GuidelineFactRow]]) -> list[GuidelineFactRow]:
out: list[GuidelineFactRow] = []
for k in range(max((len(g) for g in groups), default=0)):
out += [g[k] for g in groups if k < len(g)]
return out
def guideline_facts(
con: Any,
store: Any,
family: Any,
*,
ask: Callable | None = None,
log: RunLog | None = None,
limit: int = 0,
retry_failed: bool = False,
replay_model: str | None = None,
counts: dict[str, int] | None = None,
) -> list[GuidelineFactRow]:
"""Facts for *family*'s codes. The deterministic ones need only the
parsed tables; scope points and the Panel action go through the ledger
*log* (``ask`` runs new units, ``replay_model`` only reads the finished
ones). *counts* receives the run counts plus ``unpaged``, the number of
facts cited by section because no page was found."""
run = counts if counts is not None else {}
run.update(done=0, skipped=0, failed=0, failed_pending=0, unpaged=0)
rows = _cpt(con, family.codes) if family.codes else []
if not rows:
return []
years = sorted({r["year"] for r in rows})
pages = {
y: load_pages(store, next(r["item"] for r in rows if r["year"] == y))
for y in years
}
labelled = {y: p or [] for y, p in pages.items()}
facts = _facts(family.key, rows, labelled, run)
model = ask.model if ask is not None else replay_model
if model is None:
return facts
jobs = _scope_jobs(rows, _guidelines(con, years), labelled, run)
jobs += _panel_jobs(store, family.codes)
for j in jobs:
j["hash"] = input_hash(j["user"], j["system"])
log = log or RunLog(ledger_path("guideline", family.key))
if ask is not None:
counts_run = run_units(
[(j["unit"], j["hash"], lambda j=j: _ask_job(ask, j)) for j in jobs],
log,
model=model,
version=GUIDELINE_PROMPT_VERSION,
limit=limit,
retry_failed=retry_failed,
)
run.update(counts_run)
extractor = f"model:{model}@{GUIDELINE_PROMPT_VERSION}"
scope: dict[int, list[list[GuidelineFactRow]]] = {}
for j in jobs:
entry = log.get(j["unit"], j["hash"], model, GUIDELINE_PROMPT_VERSION)
if entry is None or entry.output is None:
continue
mine = [
GuidelineFactRow(
family.key, j["code"], j["edition"],
"panel_action" if j["unit"].startswith("panel:") else "scope_point",
s, j["item"], j["locator"], extractor,
)
for s in guarded_points(entry.output, j["guide"])
] # fmt: skip
if j["unit"].startswith("panel:"):
facts += mine[:1]
else:
scope.setdefault(j["edition"], []).append(mine)
for groups in scope.values():
facts += _interleave(groups)[:MAX_POINTS]
return facts
# ── the stance coding text ───────────────────────────────────────────
def cpt_change_text(
facts: Sequence[GuidelineFactRow], year: int, base_codes: Sequence[str]
) -> str:
"""What the CPT books say changed for a rule *year*, from stored facts
only ("" when they say nothing). It compares the newest book before the
year with the first book on or after it, and speaks only for the first
rule year after the older book. Each scope point carries its (edition,
page)."""
from pfs.stance import _compact # noqa: PLC0415 - stance imports this module
basis = [r for r in facts if r.fact == "selection_basis"]
editions = sorted({r.edition_year for r in basis})
newer = [e for e in editions if e >= year]
older = [e for e in editions if e < year]
if not newer or not older:
return ""
eff, prior = min(newer), max(older)
if year != prior + 1:
return ""
def of(edition: int, fact: str) -> dict[str, str]:
return {
r.code: r.value
for r in facts
if r.edition_year == edition and r.fact == fact
}
new_b, old_b = of(eff, "selection_basis"), of(prior, "selection_basis")
new_t = {**of(eff, "typical_time_min"), **of(eff, "time_threshold_min")}
old_t = {**of(prior, "typical_time_min"), **of(prior, "time_threshold_min")}
gone = sorted(
r.code
for r in facts
if r.fact == "deleted_in_edition" and prior < r.edition_year <= eff
)
if not gone and new_b == {c: old_b.get(c) for c in new_b} and new_t == old_t:
return ""
parts = []
for value in sorted(set(new_b.values())):
codes = sorted(c for c, v in new_b.items() if v == value)
old = sorted(
{_BASIS_LABEL[old_b[c]] for c in codes if old_b.get(c, value) != value}
)
text = (
f"{_compact(codes)} {'is' if len(codes) == 1 else 'are'} selected by "
f"{_BASIS_LABEL[value]}"
)
if old:
text += f" (CPT {prior}: {' / '.join(old)})"
parts.append(text)
if new_t:
kind = (
"total-time thresholds"
if of(eff, "time_threshold_min")
else "typical times"
)
parts.append(
f"{kind} "
+ ", ".join(f"{c} {n}" for c, n in sorted(new_t.items()))
+ " minutes"
)
if gone:
parts.append(f"{_compact(gone)} not listed in the CPT {eff} book")
text = f"CPT books on file, {prior} and {eff}: " + "; ".join(parts)
base = set(base_codes)
scope = sorted(
(r for r in facts if r.fact == "scope_point" and r.edition_year == eff
and r.code.split("-")[0] in base),
key=lambda r: (r.cite_locator, r.value),
)[:2] # fmt: skip
if scope:
text += ". Scope: " + "; ".join(
f"{r.value} (CPT {eff}, {r.cite_locator})" for r in scope
)
return text

View File

@@ -27,19 +27,41 @@ from pfs.codetables import (
CommenterRow,
ReactionRow,
StanceRow,
is_missing_table_error,
read_events,
read_guideline_facts,
read_rounds,
)
from pfs.descriptors import rule_year_of
from pfs.families import code_pattern, codes_in
from pfs.guideline_facts import cpt_change_text
from pfs.lineage import _expand_ranges
from pfs.rounds import rule_items
from pfs.runlog import RunLog, input_hash, run_units
TASK = "stance"
METHODS = ("multi", "per-event")
#: one ledger version per method: a prompt or method change is a new version
PROMPT_VERSIONS = {"multi": "stance-v4", "per-event": "stance-v4-per-event"}
#: prompt generations: v5 (R69/R74) builds the coding event from the CPT
#: guideline facts (never from keyword paragraphs alone) and picks a link's
#: relevance words by its kind; v4 keeps the earlier texts so its ledger
#: still replays
GENERATIONS = ("stance-v4", "stance-v5")
DEFAULT_GENERATION = "stance-v5"
def prompt_version(method: str, generation: str | None = None) -> str:
"""The ledger version of *method* under *generation* (default: shipped):
a prompt or method change is a new version."""
gen = generation or DEFAULT_GENERATION
return gen if method == "multi" else f"{gen}-per-event"
def guideline_text(generation: str | None = None) -> bool:
"""Whether *generation* states CPT guideline facts (v5 onward)."""
return (generation or DEFAULT_GENERATION) != "stance-v4"
PROMPT_VERSIONS = {m: prompt_version(m) for m in ("multi", "per-event")}
DEFAULT_METHOD = "multi"
DEFAULT_MODEL = "large"
STANCE_PROMPT_VERSION = PROMPT_VERSIONS[DEFAULT_METHOD]
@@ -220,13 +242,34 @@ def _all_paragraphs(store: Any, rule_year: int) -> list[tuple[str, int, str]]:
]
def _facts(con: Any, family: str) -> list:
try:
return read_guideline_facts(con, family)
except Exception as exc: # noqa: BLE001 - only a missing table is tolerated
if is_missing_table_error(exc):
return []
raise
def docket_events(
con: Any, family: Any, rule_year: int, store: Any = None
con: Any,
family: Any,
rule_year: int,
store: Any = None,
*,
guidelines: bool | None = None,
) -> list[EventChoice]:
"""The family events a docket's rule touched, each with a deterministic
text of what CMS proposed (R61), always ending in ``other``. *store*
(bib) supplies the FR paragraphs behind the telehealth and link events;
without it only stored lineage rows are used."""
without it only stored lineage rows are used. With *guidelines* (default:
the shipped generation's; v5, R74) the coding event exists only when the
year has coding facts: a CPT guideline-fact edition change, a deletion or
a created/deleted/cpt_panel/descriptor lineage event; a paragraph that
merely matches the keywords never makes one, and its text states the
facts with their (edition, page) cites."""
if guidelines is None:
guidelines = guideline_text()
key = family.key
def ev(slug: str, text: str) -> EventChoice:
@@ -281,7 +324,16 @@ def docket_events(
deleted = sorted(m.code for m in family.members if m.until == rule_year - 1)
panel = sorted({(e.code, e.kind) for e in events if e.kind in _CODING_KINDS})
coding_paras = _rule_paragraphs(paras, names, _CODING_WORDS, phrases, _TIME_WORD)
if deleted or panel or coding_paras:
cpt = (
cpt_change_text(
_facts(con, key),
rule_year,
[m.code for m in family.members if m.role == "base"],
)
if guidelines
else ""
)
if deleted or panel or cpt or (coding_paras and not guidelines):
bits = []
if deleted:
kept = sorted(
@@ -302,6 +354,8 @@ def docket_events(
for k in kinds
)
)
if cpt:
bits.append(cpt)
text = "Coding changes: " + ". ".join(bits) if bits else "Coding changes"
out.append(ev("coding", cited(text, _CODING_WORDS, _TIME_WORD)))
tele = sorted({e.code for e in events if e.kind == "telehealth_list"})
@@ -504,11 +558,26 @@ def _any(words: Sequence[str]) -> re.Pattern[str]:
return re.compile("|".join(words), re.I)
def event_subjects(family: Any, events: Sequence[EventChoice]) -> dict[str, Subject]:
#: relevance words of a linked code by its kind (R74c, v5); v4 used
#: "prolonged" for every link
LINK_WORDS = {
"prolonged-add-on": ["prolonged"],
"add-on": ["add-on", "complexity", "longitudinal"],
"modifier": ["modifier"],
}
def event_subjects(
family: Any, events: Sequence[EventChoice], *, by_kind: bool | None = None
) -> dict[str, Subject]:
"""The relevance ``Subject`` of each event of *family*, by its slug (R65).
R67/R67a: the window must name the event's subject AND this family -- one
of its codes (ranges expanded), the code or alias of a link offered among
*events*, or a pair phrase. A family code is also a coding subject."""
*events*, or a pair phrase. A family code is also a coding subject. With
*by_kind* (default: the shipped generation's) a link's own words depend on
its kind (``LINK_WORDS``)."""
if by_kind is None:
by_kind = guideline_text()
codes = code_pattern(family.codes)
phrases = (
_any([re.escape(x) for x in family.pair_phrases])
@@ -563,8 +632,12 @@ def event_subjects(family: Any, events: Sequence[EventChoice]) -> dict[str, Subj
# its subject is this family's own codes or pair phrases
sub = Subject(_NEVER, codes, phrases)
else:
kind = links[slug].kind if slug in links else ""
words = (
LINK_WORDS[kind] if by_kind and kind in LINK_WORDS else ["prolonged"]
)
sub = Subject(
_any([*(re.escape(n) for n in link_names[slug]), "prolonged"]),
_any([*(re.escape(n) for n in link_names[slug]), *words]),
family=named,
)
out[e.event_key] = sub
@@ -664,6 +737,7 @@ def stances_for(
family: str,
docket: str,
method: str = DEFAULT_METHOD,
generation: str | None = None,
model: str | None = None,
subjects: Mapping[str, Subject] | None = None,
limit: int = 0,
@@ -678,7 +752,7 @@ def stances_for(
counts (calls) plus ``pending`` (comments with an unanswered call) and
``no_text`` (a commenter whose comment text is not found)."""
model = model or getattr(ask, "model", "unknown")
version = PROMPT_VERSIONS[method]
version = prompt_version(method, generation)
extractor = f"model:{model}@{version}"
keys = [c.item_key for c in commenters if c.item_key in texts]
clean = {k: clean_text(texts[k]) for k in keys}

View File

@@ -137,8 +137,9 @@ def extract_text(path: str | Path) -> str:
#: the AMA books mark each printed page with an empty ``<span id="page_12"/>``
#: (the 2022 Professional edition uses ``<a id="page_12"/>``)
#: (labels are roman numerals for front matter, arabic after)
_PAGE_SPAN = re.compile(r'<span id="page_([^"\x00]*)"\s*(?:/>|></span>)')
_PAGE_SPAN = re.compile(r'<(?:span|a) id="page_([^"\x00]*)"\s*(?:/>|></(?:span|a)>)')
_PAGE_MARK = re.compile(r"\x00([^\x00]*)\x00")

View File

@@ -2020,7 +2020,7 @@ class TestStance:
monkeypatch.setattr(
pfs_cli,
"docket_events",
lambda con_, fam, year, store_: [
lambda con_, fam, year, store_, **kw: [
EventChoice("HOME-VISITS:2023:G0318", "g", year),
EventChoice("HOME-VISITS:2023:other", "o", year),
],
@@ -2355,7 +2355,7 @@ class TestStanceEval:
monkeypatch.setattr(
pfs_cli,
"docket_events",
lambda con_, fam, year, store_: [
lambda con_, fam, year, store_, **kw: [
EventChoice("HOME-VISITS:2023:G0318", "g", year),
EventChoice("HOME-VISITS:2023:other", "o", year),
],
@@ -2425,6 +2425,29 @@ class TestStanceEval:
class TestStanceMethodRecord:
def test_v5_generation_is_recorded_and_threaded(self, con, monkeypatch):
t = TestStance()
seen = t._patch(con, monkeypatch)
from pfs.stance import EventChoice
flags = []
def events(c_, f, y, s_, **kw):
flags.append(kw["guidelines"])
return [
EventChoice("HOME-VISITS:2023:G0318", "g", y),
EventChoice("HOME-VISITS:2023:other", "o", y),
]
monkeypatch.setattr(pfs_cli, "docket_events", events)
res = runner.invoke(
app, t._args("--model", "large", "--generation", "stance-v5", "--write")
)
assert res.exit_code == 0, res.output
assert flags == [True] and seen["generation"] == "stance-v5"
d1 = {r.period: r for r in read_reaction(con._real, "HOME-VISITS")}["D1"]
assert d1.stance_method == "stance-v5:qwen-x"
def test_write_records_method_and_golden_agreement(self, con, monkeypatch):
t = TestStance()
seen = t._patch(con, monkeypatch)
@@ -2432,7 +2455,7 @@ class TestStanceMethodRecord:
assert res.exit_code == 0, res.output
got = {r.period: r for r in read_reaction(con._real, "HOME-VISITS")}
d1 = got["D1"]
assert d1.stance_method == f"{pfs_cli.PROMPT_VERSIONS['multi']}:qwen-x"
assert d1.stance_method == f"{pfs_cli.prompt_version('multi')}:qwen-x"
# R66a: the measurement is the stance_eval JSON; the single figure is gone
assert d1.stance_agreement is None
assert json.loads(d1.stance_eval) == {
@@ -2572,3 +2595,103 @@ class TestStanceEvalOffline:
)
assert "multi on L (no relevance filter)" in res.output
assert "incomplete" in res.output
class TestGuidelineFacts:
def _row(self, **kw):
from pfs.codetables import GuidelineFactRow
base = dict(
family="HOME-VISITS", code="99341", edition_year=2024,
fact="selection_basis", value="mdm_or_time", cite_item="B",
cite_locator="p. 1", extractor="cpt-book",
) # fmt: skip
return GuidelineFactRow(**{**base, **kw})
def _patch(self, monkeypatch, seen, asker=lambda: "ASK"):
rows = [
self._row(),
self._row(code="99342"),
self._row(fact="mdm_level", value="low"),
]
def fake(con, store, fam, **kw):
seen.update(kw, key=fam.key)
kw["counts"].update(
done=2, skipped=1, failed=0, failed_pending=0, unpaged=0
)
return rows
monkeypatch.setattr(pfs_cli, "guideline_facts", fake)
monkeypatch.setattr(pfs_cli, "_asker", asker)
monkeypatch.setattr(pfs_cli, "_model_name", lambda large=False: "qwen-x")
monkeypatch.setattr(
pfs_cli, "ledger_path", lambda t, f: Path("/nonexistent") / f"{t}-{f}"
)
def test_write(self, con, monkeypatch):
from pfs.codetables import read_guideline_facts
seen = {}
self._patch(monkeypatch, seen)
res = runner.invoke(
app,
[
"pfs",
"guideline-facts",
"--family",
"home-visits",
"--limit",
"3",
"--write",
],
)
assert res.exit_code == 0, res.output
assert (
seen["ask"] == "ASK" and seen["limit"] == 3 and seen["replay_model"] is None
)
assert (
"2024 selection_basis: 2" in res.output
and "2024 mdm_level: 1" in res.output
)
assert "facts: 3; done 2, skipped 1" in res.output
assert "wrote 3 facts" in res.output and con.published
assert len(read_guideline_facts(con._real, "HOME-VISITS")) == 3
def test_no_write_and_replay(self, con, monkeypatch):
seen = {}
self._patch(monkeypatch, seen)
res = runner.invoke(
app, ["pfs", "guideline-facts", "--family", "HOME-VISITS", "--no-llm"]
)
assert res.exit_code == 0 and "wrote" not in res.output
assert seen["ask"] is None and seen["replay_model"] == "qwen-x"
def test_no_host_replays(self, con, monkeypatch):
seen = {}
def down():
raise RuntimeError("no hosts")
self._patch(monkeypatch, seen, asker=down)
res = runner.invoke(app, ["pfs", "guideline-facts", "--family", "HOME-VISITS"])
assert res.exit_code == 0 and "no model host available" in res.output
assert seen["ask"] is None
def test_unknown_family(self, con):
res = runner.invoke(app, ["pfs", "guideline-facts", "--family", "NOPE"])
assert res.exit_code != 0
class TestStanceGeneration:
def test_bad_generation(self, con):
for cmd, extra in (
("stance", ["--docket", "D1"]),
("stance-eval", ["--golden", "x.json"]),
):
res = runner.invoke(
app,
["pfs", cmd, "--generation", "stance-v9", *extra]
+ (["--family", "HOME-VISITS"] if cmd == "stance" else []),
)
assert res.exit_code != 0 and "--generation" in res.output

View File

@@ -0,0 +1,837 @@
"""pfs.guideline_facts: facts from the licensed CPT books (task 9b, R69).
Every fixture text is invented guideline-like prose, never real CPT text."""
from __future__ import annotations
from types import SimpleNamespace
import duckdb
import pytest
from pfs import guideline_facts as gf
from pfs.codetables import (
GuidelineFactRow,
ensure_tables,
read_guideline_facts,
write_guideline_facts,
)
from pfs.runlog import RunLog
FAM = SimpleNamespace(key="HV", codes=("70001", "70002", "70003"))
OLD = (
"Zed call for a fresh case, needing these 3 key components: An alpha past "
"review; An alpha scan; and; Straightforward medical decision making. Blorp "
"snarf wibble. Typically, 20 minutes elapse."
)
OLD2 = (
"Zed call for a repeat case, needing 2 of these 3 key components: An interval "
"review; Zed decision making of moderate to high complexity. Blorp snarf. "
"Typically, 60 minutes elapse."
)
OLD3 = (
"Zed call for a case needing Zed decision making of low complexity. Blorp. "
"Typically, 30 minutes elapse."
)
NEW = (
"Zed or Quux call for a fresh case, needing a medically appropriate history "
"and moderate level of medical decision making. Count clock time per "
"encounter date; 40 minutes must be met or exceeded."
)
GUIDE = (
"Zed services are reported for care furnished at the patient place of "
"residence. Mileage between stops is never counted toward time."
)
def _con():
con = duckdb.connect(":memory:")
ensure_tables(con)
return con
def _code(con, year, key, code, sec, desc, elements=(), addon=False):
con.execute(
"INSERT INTO pfs.cpt_code (edition_year, item_key, code, sec_id, descriptor, "
"elements, addon) VALUES (?,?,?,?,?,?,?)",
[year, key, code, sec, desc, list(elements), addon],
)
def _sec(con, year, key, sec, path, guideline=""):
con.execute(
"INSERT INTO pfs.cpt_section (edition_year, item_key, sec_id, level, title, "
"path, guideline) VALUES (?,?,?,?,?,?,?)",
[year, key, sec, len(path), path[-1], path, guideline],
)
@pytest.fixture
def con():
c = _con()
# 2021: old style; 2024: new style, 70003 gone
_sec(c, 2021, "B21", "s1", ["Chap", "Zed Services"], GUIDE)
_sec(c, 2021, "B21", "s2", ["Chap", "Zed Services", "New"])
_sec(
c,
2024,
"B24",
"t1",
["Chap", "Zed or Quux Services"],
GUIDE + " Extra point here.",
)
_sec(c, 2024, "B24", "t2", ["Chap", "Zed or Quux Services", "New"])
_code(
c,
2021,
"B21",
"70001",
"s2",
OLD,
["An alpha history;", "An alpha examination; and"],
)
_code(c, 2021, "B21", "70002", "s2", OLD2, ["An interval history;"])
_code(c, 2021, "B21", "70003", "s2", OLD3)
_code(c, 2024, "B24", "70001", "t2", NEW)
_code(
c,
2024,
"B24",
"70002",
"t2",
NEW.replace("moderate level", "high level"),
addon=True,
)
yield c
c.close()
# ── value parsers ────────────────────────────────────────────────────
def test_selection_basis():
assert gf.selection_basis(OLD, ["x"]) == "history_exam_mdm"
assert gf.selection_basis("requires 3 key components: x", []) == "history_exam_mdm"
assert gf.selection_basis(NEW, []) == "mdm_or_time"
assert gf.selection_basis("something else", []) is None
@pytest.mark.parametrize(
("text", "level"),
[
("Straightforward medical decision making.", "straightforward"),
("and straightforward Medical Decision Making", "straightforward"),
("Zed decision making of low complexity", "low"),
("Zed decision making of moderate complexity", "moderate"),
("Zed decision making of high complexity", "high"),
("Zed decision making of moderate to high complexity", "moderate_to_high"),
("a low level of medical decision making", "low"),
("a moderate level of medical decision making", "moderate"),
("a high level of medical decision making", "high"),
("no such words", None),
],
)
def test_mdm_level(text, level):
assert gf.mdm_level(text) == level
def test_time_facts():
assert gf.time_facts(OLD) == {"typical_time_min": 20}
assert gf.time_facts(NEW) == {"time_threshold_min": 40}
assert gf.time_facts("nothing") == {}
# ── page finding ─────────────────────────────────────────────────────
def test_norm_strips_markers():
assert gf.norm("a ▶b◀\r\n\r\n c ┃") == "a b c ┃"
PAGES = [
("i", "front matter"),
("21", "Intro.\n\n70001\n\nZed call for a fresh case, needing"),
("22", "70002\n\n▶Zed call for a repeat case, needing 2 of"),
]
def test_code_page():
assert gf.code_page(PAGES, "70001", OLD) == "21"
assert gf.code_page(PAGES, "70002", OLD2) == "22"
assert gf.code_page(PAGES, "70009", OLD) is None
assert gf.code_page([("", "70001 Zed call for")], "70001", OLD) is None
def test_sentence_page():
pages = [
("1", "Mileage rule."),
("2", "other"),
("3", "Mileage rule."),
("4", "70001 Zed"),
("5", "Mileage rule."),
]
# nearest hit at or before the code page, not the first one in the book
assert gf.sentence_page(pages, "Mileage rule", 3) == 2
# nothing before: the first hit just after
assert gf.sentence_page(pages, "Mileage rule", 3 - 3) == 0
assert (
gf.sentence_page([("1", "x"), ("2", "Late text"), ("3", "y")], "Late text", 0)
== 1
)
assert gf.sentence_page(pages, "absent text", 3) is None
assert gf.sentence_page([("", "Mileage rule")], "Mileage rule", 0) is None
def test_find_page_monotonic():
assert gf.find_page(PAGES, "Zed call for a repeat", 0) == 2
assert gf.find_page(PAGES, "Zed call for a repeat", 3) is None
assert gf.find_page(PAGES, "zzz", 0) is None
# ── copy guard ───────────────────────────────────────────────────────
SENTS = [
"Mileage between stops is never counted toward time.",
"Zed visits happen in the residence of the patient, not licensed as a clinic.",
"Accept deletion of codes 70003 and 70004; revision of codes 70001, 70002.",
]
def _pt(k, summary):
return {"sentence": k, "summary": summary}
def test_guarded_points():
out = {
"points": [
_pt(
1, "Travel between stops is excluded from the time count."
), # unseen word
_pt(1, "Mileage between stops never counts toward time."),
_pt(1, "Mileage between stops is never counted toward time."), # copy
_pt(1, "x" * 241),
_pt(1, " "),
_pt(1, "Mileage between stops never counts toward time."), # duplicate
_pt(1, "Applies to 99 stops."), # number not in the passage
_pt(1, 5),
_pt(9, "Mileage between stops never counts toward time."), # bad sentence
_pt(True, "Mileage between stops never counts toward time."),
_pt(1, "The text does not say anything about mileage."),
_pt(1, "No rules about mileage are given."),
"junk",
{"summary": "no sentence"},
_pt(2, "Zed visits happen at the patient residence, not licensed clinic."),
_pt(3, "Mileage stops between."), # words from a sentence two away
_pt(1, "No mileage is counted toward time."),
]
}
assert gf.guarded_points(out, SENTS) == [
"Mileage between stops never counts toward time.",
"Zed visits happen at the patient residence, not licensed clinic.",
"No mileage is counted toward time.",
]
assert gf.guarded(out, SENTS)[0][0] == 1
assert gf.guarded_points({"points": "bad"}, SENTS) == []
assert gf.guarded_points({}, SENTS) == []
def test_nfkc_copy_guard():
# full-width and curly characters cannot slip a copy past the guard
sents = ["Zed visits happen in the residence of the patient every single day."]
copy = "Zed visits happen in the residence of the patient every single day."
wide = copy.replace("Zed", "\uff3a\uff45\uff44").replace("'", "\u2019")
assert gf.guarded_points({"points": [_pt(1, wide)]}, sents) == []
def test_codes_must_sit_in_the_same_action_clause():
sents = [SENTS[2]]
ok = "Deletion applies to 70003 and 70004; revision applies to 70001 and 70002."
assert gf.guarded_points({"points": [_pt(1, ok)]}, sents) == [ok]
# 70001-70004 under "revision" would sweep in the deleted 70003
bad = "Revision applies to 70001-70004."
assert gf.guarded_points({"points": [_pt(1, bad)]}, sents) == []
# a clause with no action word needs the code anywhere in the window
assert gf.guarded_points({"points": [_pt(1, "Codes 70001 and 70002.")]}, sents)
assert not gf.guarded_points({"points": [_pt(1, "Codes 70009 revision.")]}, sents)
def test_stem_and_content():
assert gf._stem("services") == gf._stem("service")
assert gf._stem("residences") == gf._stem("residence")
assert gf._stem("deletion") == gf._stem("deleted") == gf._stem("deletions")
assert gf._stem("facilities") == gf._stem("facility")
assert gf._content("The residences of patients") == ["residenc", "patient"]
assert gf.sentences_of("One two. Three four.") == ["One two.", "Three four."]
# ── deterministic facts ──────────────────────────────────────────────
def _pages(label_text):
return [(lab, txt) for lab, txt in label_text]
B21 = [
(
"5",
"70001\n\nZed call for a fresh case, needing\n\n70002\n\nZed call for a repeat case, needing 2 of",
),
("6", "70003\n\nZed call for a case needing Zed decision"),
]
B24 = [
(
"9",
"70001\n\nZed or Quux call for a fresh case, needing\n\n70002\n\nZed or Quux call for a fresh case, needing a",
),
]
@pytest.fixture
def books(monkeypatch):
pages = {"B21": B21, "B24": B24}
monkeypatch.setattr(gf, "load_pages", lambda store, key: pages.get(key))
monkeypatch.setattr(gf, "load_panel", lambda store, key: [])
return pages
def _by(rows, **kw):
return [r for r in rows if all(getattr(r, k) == v for k, v in kw.items())]
def test_deterministic_facts(con, books):
rows = gf.guideline_facts(con, object(), FAM)
one21 = {r.fact: r for r in rows if r.code == "70001" and r.edition_year == 2021}
assert one21["selection_basis"].value == "history_exam_mdm"
assert one21["mdm_level"].value == "straightforward"
assert one21["typical_time_min"].value == "20"
assert "time_threshold_min" not in one21
assert one21["selection_basis"].cite_item == "B21"
assert one21["selection_basis"].cite_locator == "p. 5"
assert one21["selection_basis"].extractor == "cpt-book"
assert (
_by(rows, code="70002", edition_year=2021, fact="mdm_level")[0].value
== "moderate_to_high"
)
assert (
_by(rows, code="70003", edition_year=2021, fact="mdm_level")[0].value == "low"
)
assert (
_by(rows, code="70003", edition_year=2021, fact="mdm_level")[0].cite_locator
== "p. 6"
)
new = {
r.fact: r.value for r in rows if r.code == "70001" and r.edition_year == 2024
}
assert new == {
"selection_basis": "mdm_or_time",
"mdm_level": "moderate",
"time_threshold_min": "40",
}
# add-on only when true
assert _by(rows, code="70002", edition_year=2024, fact="addon")[0].value == "true"
assert not _by(rows, code="70001", fact="addon")
# 70003 was in 2021 and is absent from 2024
gone = _by(rows, fact="deleted_in_edition")
assert [(r.code, r.edition_year, r.value) for r in gone] == [
("70003", 2024, "2021")
]
assert gone[0].cite_item == "B24"
assert gone[0].cite_locator == "p. 9"
def test_section_locator_when_no_page_markers(con, monkeypatch):
monkeypatch.setattr(
gf, "load_pages", lambda store, key: [("", "text with no page labels")]
)
monkeypatch.setattr(gf, "load_panel", lambda store, key: [])
rows = gf.guideline_facts(con, object(), FAM)
r = _by(rows, code="70001", edition_year=2021, fact="selection_basis")[0]
assert r.cite_locator == "Chap > Zed Services > New"
gone = _by(rows, fact="deleted_in_edition")[0]
assert gone.cite_locator == "Chap > Zed or Quux Services > New"
def test_page_not_found_falls_back_to_section(con, monkeypatch):
monkeypatch.setattr(gf, "load_pages", lambda store, key: [("3", "no codes here")])
monkeypatch.setattr(gf, "load_panel", lambda store, key: [])
c = {}
rows = gf.guideline_facts(con, object(), FAM, counts=c)
r = _by(rows, code="70001", edition_year=2021, fact="selection_basis")[0]
assert r.cite_locator == "Chap > Zed Services > New"
assert c["unpaged"] > 0
def test_unreadable_book_is_skipped(con, monkeypatch):
monkeypatch.setattr(gf, "load_pages", lambda store, key: None)
monkeypatch.setattr(gf, "load_panel", lambda store, key: None)
rows = gf.guideline_facts(con, object(), FAM)
r = _by(rows, code="70001", edition_year=2021, fact="selection_basis")[0]
assert r.cite_locator == "Chap > Zed Services > New"
def test_no_cpt_rows():
assert gf.guideline_facts(_con(), object(), FAM) == []
assert gf.guideline_facts(duckdb.connect(":memory:"), object(), FAM) == []
# ── deletions dated by CPT Changes ───────────────────────────────────
CHANGES = [
("7", "Preface."),
(
"48",
"\u25b6(70003 has been deleted. Use the Zed codes.)\u25c0\n\nRationale\n\n"
"Blorp snarf wibble.",
),
("49", "Rationale\n\nCode 70003 has been deleted by the Zed panel."),
]
def test_deletion_dated_by_changes_book(con, monkeypatch):
pages = {"B21": B21, "B24": B24, gf.CHANGES_ITEM: CHANGES}
monkeypatch.setattr(gf, "load_pages", lambda store, key: pages.get(key))
monkeypatch.setattr(gf, "load_panel", lambda store, key: [])
(gone,) = _by(gf.guideline_facts(con, object(), FAM), fact="deleted_in_edition")
assert (gone.code, gone.edition_year, gone.value) == ("70003", 2023, "2021")
assert (gone.cite_item, gone.cite_locator) == (gf.CHANGES_ITEM, "p. 48")
def test_deletion_falls_back_to_the_later_books_own_note(con, monkeypatch):
b24 = [*B24, ("10", "(70003 has been deleted. See the Zed codes)")]
pages = {"B21": B21, "B24": b24, gf.CHANGES_ITEM: [("5", "no code here")]}
monkeypatch.setattr(gf, "load_pages", lambda store, key: pages.get(key))
monkeypatch.setattr(gf, "load_panel", lambda store, key: [])
(gone,) = _by(gf.guideline_facts(con, object(), FAM), fact="deleted_in_edition")
assert (gone.edition_year, gone.cite_item, gone.cite_locator) == (
2024,
"B24",
"p. 10",
)
# ── scope points (model) ─────────────────────────────────────────────
P1 = "Zed services cover care furnished at the residence."
P2 = "Mileage between stops never counts toward time."
def ask_with(points, calls=None):
"""Answers each call with *points*: ``(sentence, summary)`` pairs, or a
callable of the user prompt."""
def ask(system, user, schema):
if calls is not None:
calls.append((system, user, schema))
pts = points(user) if callable(points) else points
return {"points": [{"sentence": k, "summary": p} for k, p in pts]}
ask.model = "qwen-test"
return ask
def by_prompt(user):
return [(1, P1)] if "Zed services" in user else [(1, P2)]
def test_scope_points_through_ledger(con, books, tmp_path):
calls = []
log = RunLog(tmp_path / "l.jsonl")
ask = ask_with([(1, P1), (2, P2)], calls)
c = {}
rows = gf.guideline_facts(con, object(), FAM, ask=ask, log=log, counts=c)
pts = _by(rows, fact="scope_point")
assert {(r.edition_year, r.code) for r in pts} == {
(2021, "70001-70003"),
(2024, "70001-70002"),
}
assert all(
r.extractor == f"model:qwen-test@{gf.GUIDELINE_PROMPT_VERSION}" for r in pts
)
assert gf.GUIDELINE_PROMPT_VERSION == "guideline-v2"
assert len(calls) == 2 * gf.ATTEMPTS and c["done"] == 2 # 2 points < ENOUGH
assert "[1] Zed services" in calls[0][1] and "[2] Mileage" in calls[0][1]
assert "time" not in calls[0][0].replace("sometimes", "") # no time steer
assert calls[0][2]["properties"]["points"]["items"]["required"] == [
"sentence",
"summary",
]
# the ledger holds the kept paraphrases with their sentence, never the book text
ledger = (tmp_path / "l.jsonl").read_text()
assert '"sentence": 1' in ledger and "place of residence" not in ledger
calls.clear()
gf.guideline_facts(con, object(), FAM, ask=ask, log=log)
assert calls == [] # resume: no new calls
rows2 = gf.guideline_facts(con, object(), FAM, log=log, replay_model="qwen-test")
assert _by(rows2, fact="scope_point") == pts
WORDS = (
"Zed care furnished.|Residence care furnished.|Patient place residence.|"
"Zed reported care.|Zed patient care.|Care furnished residence.|"
"Zed place residence.|Reported care place.|Zed furnished patient."
).split("|")
def test_scope_points_capped_at_six(con, books, tmp_path):
ask = ask_with([(1, w) for w in WORDS])
rows = gf.guideline_facts(
con, object(), FAM, ask=ask, log=RunLog(tmp_path / "l.jsonl")
)
assert len(_by(rows, fact="scope_point", edition_year=2021)) == 6
def test_scope_unguarded_dropped_and_failed(con, books, tmp_path):
log = RunLog(tmp_path / "l.jsonl")
copy = "Zed services are reported for care furnished at the patient place of residence."
rows = gf.guideline_facts(con, object(), FAM, ask=ask_with([(1, copy)]), log=log)
assert not _by(rows, fact="scope_point")
def fail(s, u, sc):
return None
fail.model = "qwen-test"
c = {}
gf.guideline_facts(
con, object(), FAM, ask=fail, log=RunLog(tmp_path / "m.jsonl"), counts=c
)
assert c["failed"] == 2
def test_scope_limit(con, books, tmp_path):
calls = []
gf.guideline_facts(
con, object(), FAM, ask=ask_with([(1, P1)], calls),
log=RunLog(tmp_path / "l.jsonl"), limit=1,
) # fmt: skip
assert len(calls) == gf.ATTEMPTS # one unit, asked until ENOUGH or ATTEMPTS
def test_scope_without_page_markers(con, monkeypatch, tmp_path):
monkeypatch.setattr(gf, "load_pages", lambda store, key: [("", "text")])
monkeypatch.setattr(gf, "load_panel", lambda store, key: [])
rows = gf.guideline_facts(
con, object(), FAM, ask=ask_with([(1, P1)]), log=RunLog(tmp_path / "l.jsonl")
)
pt = _by(rows, fact="scope_point", edition_year=2021)[0]
assert pt.cite_locator == "Chap > Zed Services"
def test_scope_points_split_by_page(con, monkeypatch, tmp_path):
pages = {
"B21": [
("3", "Zed services are reported for care furnished elsewhere"),
("5", "Zed services are reported for care furnished"),
(
"6",
"Mileage between stops is never counted toward time.\n\n70001\n\n"
"Zed call for a fresh case, needing",
),
],
"B24": [("9", "nothing")],
}
monkeypatch.setattr(gf, "load_pages", lambda store, key: pages.get(key))
monkeypatch.setattr(gf, "load_panel", lambda store, key: [])
rows = gf.guideline_facts(
con, object(), FAM, ask=ask_with(by_prompt), log=RunLog(tmp_path / "l.jsonl")
)
locs = sorted(
r.cite_locator for r in _by(rows, fact="scope_point", edition_year=2021)
)
assert locs == ["p. 5", "p. 6"]
# ── panel action ─────────────────────────────────────────────────────
ENTRY = (
"Accept deletion of codes 70003 and 70004; revision of codes 70001, 70002, and "
"the Zed subsection heading. January 1, 2023 "
)
PANEL = [
"Updated\n\n9\nOther Services\n70005\nAccept a thing\nJanuary 1, 2023\n",
f"Updated\n10 \nZed and Quux Services\nD70003\n70001\n70002\n{ENTRY}\n11 \nLater Tab\n70009\nAccept\n",
]
PANEL_POINT = "Deletion applies to 70003 and 70004; revision applies to 70001 and 70002 with the subsection heading."
def test_panel_entry():
tab, page, text = gf.panel_entry(PANEL, "Zed and Quux Services")
assert (tab, page) == ("10", 2)
assert "deletion of codes 70003" in text and "Later Tab" not in text
assert gf.panel_entry(PANEL, "Nothing Services") is None
assert gf.panel_entry(["x"], "x") is None
def test_panel_action_row(con, monkeypatch, tmp_path):
monkeypatch.setattr(gf, "load_pages", lambda store, key: [("1", "t")])
monkeypatch.setattr(gf, "load_panel", lambda store, key: PANEL)
monkeypatch.setattr(gf, "PANEL_TITLES", ("Zed and Quux Services",))
ask = ask_with([(1, PANEL_POINT)])
rows = gf.guideline_facts(
con, object(), FAM, ask=ask, log=RunLog(tmp_path / "l.jsonl")
)
(row,) = _by(rows, fact="panel_action")
assert (row.code, row.cite_item) == ("70001-70003", gf.PANEL_ITEM)
assert (row.cite_locator, row.edition_year) == ("tab 10, PDF p. 2", 2023)
assert row.value == PANEL_POINT
# a paraphrase that sweeps a deleted code into the revision is dropped
bad = ask_with([(1, "Deletion applies to 70003; revision applies to 70001-70004.")])
rows = gf.guideline_facts(
con, object(), FAM, ask=bad, log=RunLog(tmp_path / "m.jsonl")
)
assert [r.extractor for r in _by(rows, fact="panel_action")] == ["cpt-panel"]
# a copied paraphrase is dropped
copy = ask_with(
[
(
1,
"Accept deletion of codes 70003 and 70004; revision of codes 70001, 70002 and more",
)
]
)
rows = gf.guideline_facts(
con, object(), FAM, ask=copy, log=RunLog(tmp_path / "n.jsonl")
)
assert [r.extractor for r in _by(rows, fact="panel_action")] == ["cpt-panel"]
# ── the stance summary ───────────────────────────────────────────────
def _fact(code, year, fact, value, loc="p. 9", item="B24"):
return GuidelineFactRow("HV", code, year, fact, value, item, loc, "cpt-book")
FACTS = [
_fact("70001", 2021, "selection_basis", "history_exam_mdm", item="B21"),
_fact("70002", 2021, "selection_basis", "history_exam_mdm", item="B21"),
_fact("70003", 2021, "selection_basis", "history_exam_mdm", item="B21"),
_fact("70001", 2024, "selection_basis", "mdm_or_time"),
_fact("70002", 2024, "selection_basis", "mdm_or_time"),
_fact("70001", 2024, "time_threshold_min", "40"),
_fact("70002", 2024, "time_threshold_min", "55"),
_fact("70003", 2023, "deleted_in_edition", "2021", "p. 48", gf.CHANGES_ITEM),
_fact(
"70001-70002", 2024, "scope_point", "Zed care sits at the residence.", "p. 8"
),
_fact(
"70001-70002", 2024, "scope_point", "Mileage never counts toward time.", "p. 9"
),
_fact(
"70001-70002", 2024, "scope_point", "Do not use these for Quux sites.", "p. 8"
),
_fact("70001-70002", 2024, "scope_point", "A fourth point.", "p. 7"),
_fact("70001-70002", 2021, "scope_point", "Old point.", "p. 2"),
_fact("70009-70010", 2024, "scope_point", "Another code range.", "p. 1"),
]
def test_change_text():
text = gf.cpt_change_text(FACTS, 2022, ["70001", "70002"])
assert text.startswith("CPT books on file, 2021 and 2024")
assert "70001 and 70002 are selected by" in text
assert "level of medical decision making or total time (CPT 2024, p. 9)" in text
assert "history, examination and medical decision making" in text
assert "(CPT 2021, p. 9:" in text
assert "70001 40, 70002 55 minutes (CPT 2024, p. 9)" in text
# the deletion is dated by CPT Changes and carries its page
assert "70003 deleted in CPT 2023 (CPT Changes 2023, p. 48)" in text
# the two scope points that state a reporting rule come first, by page
assert "Do not use these for Quux sites. (CPT 2024, p. 8); Mileage never" in text
assert "counts toward time. (CPT 2024, p. 9)" in text
assert "Zed care sits" not in text and "Old point" not in text
assert "Another code range" not in text and "fourth point" not in text
# a deletion cited to the later book names that book
late = [*FACTS[:-7], _fact("70003", 2024, "deleted_in_edition", "2021", "p. 10")]
assert "70003 deleted in CPT 2024 (CPT 2024, p. 10)" in gf.cpt_change_text(
late, 2022, ["70001"]
)
def test_change_text_none_cases():
assert gf.cpt_change_text([], 2022, ["70001"]) == ""
# only the first rule year after the older book states the change
assert gf.cpt_change_text(FACTS, 2021, ["70001"]) == ""
assert gf.cpt_change_text(FACTS, 2024, ["70001"]) == ""
# nothing newer than the book
assert gf.cpt_change_text(FACTS, 2030, ["70001"]) == ""
# no earlier book to compare
assert gf.cpt_change_text(FACTS, 2020, ["70001"]) == ""
# nothing changed between the books
same = [
_fact("70001", 2021, "selection_basis", "mdm_or_time", item="B21"),
_fact("70001", 2024, "selection_basis", "mdm_or_time"),
]
assert gf.cpt_change_text(same, 2022, ["70001"]) == ""
def test_change_text_typical_times_and_no_scope():
rows = [
_fact("70001", 2021, "selection_basis", "history_exam_mdm", item="B21"),
_fact("70001", 2021, "typical_time_min", "20", item="B21"),
_fact("70001", 2022, "selection_basis", "mdm_or_time"),
_fact("70001", 2022, "typical_time_min", "30"),
]
text = gf.cpt_change_text(rows, 2022, ["70001"])
assert text == (
"CPT books on file, 2021 and 2022: 70001 is selected by level of medical "
"decision making or total time (CPT 2022, p. 9) (CPT 2021, p. 9: history, "
"examination and medical decision making); typical times 70001 30 minutes "
"(CPT 2022, p. 9)"
)
def test_write_read_facts():
con = _con()
assert write_guideline_facts(con, "HV", FACTS) == len(FACTS)
assert write_guideline_facts(con, "HV", FACTS[:2]) == 2
assert read_guideline_facts(con, "HV") == sorted(
FACTS[:2],
key=lambda r: (r.edition_year, r.code, r.fact, r.cite_locator, r.value),
)
assert write_guideline_facts(con, "HV", []) == 0
assert read_guideline_facts(con, "HV") == []
# ── readers ──────────────────────────────────────────────────────────
def test_load_pages_and_panel(tmp_path):
import pymupdf
from bib.item import Source
from bib.store import Store
from tests.pfs.test_origin import make_epub
s = Store(":memory:", storage_dir=tmp_path / "st")
key = s.create(Source(title="Synthetic book"))
assert gf.load_pages(s, key) is None and gf.load_panel(s, key) is None
s.attach_file(key, make_epub(tmp_path / "b.epub", {"3": "Three.", "4": "Four."}))
assert gf.load_pages(s, key) == [("3", "Three."), ("4", "Four.")]
assert gf.load_panel(s, key) is None # an EPUB is not the panel PDF
pdf = tmp_path / "p.pdf"
doc = pymupdf.open()
doc.new_page().insert_text((72, 72), "First page")
doc.new_page().insert_text((72, 72), "Second page")
doc.save(pdf)
doc.close()
k2 = s.create(Source(title="Synthetic panel"))
s.attach_file(k2, pdf)
pages = gf.load_panel(s, k2)
assert [p.strip() for p in pages] == ["First page", "Second page"]
def test_other_database_errors_propagate():
class Boom:
def execute(self, *a):
raise RuntimeError("disk gone")
with pytest.raises(RuntimeError):
gf.guideline_facts(Boom(), object(), FAM)
def test_panel_entry_without_family_codes_is_skipped(con, monkeypatch, tmp_path):
monkeypatch.setattr(gf, "load_pages", lambda store, key: [("1", "t")])
monkeypatch.setattr(
gf,
"load_panel",
lambda store, key: ["x\n10 \nZed and Quux Services\nD99999\nAccept it\n"],
)
monkeypatch.setattr(gf, "PANEL_TITLES", ("Zed and Quux Services",))
rows = gf.guideline_facts(
con,
object(),
FAM,
ask=ask_with([(1, "Accept it for 70001.")]),
log=RunLog(tmp_path / "l.jsonl"),
)
assert not _by(rows, fact="panel_action")
# an entry without an effective year gets edition_year 0
monkeypatch.setattr(
gf,
"load_panel",
lambda store, key: ["x\n10 \nZed and Quux Services\n70001\nAccept it\n"],
)
rows = gf.guideline_facts(
con,
object(),
FAM,
ask=ask_with([(1, "Accept it for 70001.")]),
log=RunLog(tmp_path / "m.jsonl"),
)
assert _by(rows, fact="panel_action")[0].edition_year == 0
def test_unit_is_asked_again_until_enough_points_pass(con, books, tmp_path):
replies = iter(
[
[(1, "Zed made up words appear here.")], # fails the guards
None, # a failed reply
[(1, P1), (2, P2)],
[(1, "Zed care furnished."), (1, "Residence care furnished.")],
]
)
calls = []
def ask(system, user, schema):
calls.append(1)
pts = next(replies, None)
return (
None
if pts is None
else {"points": [{"sentence": k, "summary": p} for k, p in pts]}
)
ask.model = "qwen-test"
out = gf._ask_job(
ask,
gf._scope_jobs(
gf._cpt(con, FAM.codes),
gf._guidelines(con, [2021]),
{2021: B21},
{"unpaged": 0},
)[0],
)
assert len(calls) == 4 and len(out["points"]) == 4 # stops at ENOUGH
assert [p["summary"] for p in out["points"]][:2] == [P1, P2]
def test_panel_fallback_states_the_code_lists():
text = ENTRY
out = gf.panel_fallback(text, ["70001", "70002", "70003"])
assert out == (
"Deleted codes 70003; revised codes 70001, 70002; the matching subsection "
"headings and guidelines were also deleted or revised; effective 2023."
)
assert gf.panel_fallback("Accept a thing", ["70001"]) is None
assert gf.panel_fallback("deletion of codes 70005", ["70001"]) is None
assert "effective" not in gf.panel_fallback("deletion of codes 70001", ["70001"])
many = "deletion of codes " + ", ".join(str(70000 + 2 * i) for i in range(60)) + ";"
assert gf.panel_fallback(many, [str(70000 + 2 * i) for i in range(60)]) is None
def test_panel_action_falls_back_when_the_model_adds_nothing(
con, monkeypatch, tmp_path
):
monkeypatch.setattr(gf, "load_pages", lambda store, key: [("1", "t")])
monkeypatch.setattr(gf, "load_panel", lambda store, key: PANEL)
monkeypatch.setattr(gf, "PANEL_TITLES", ("Zed and Quux Services",))
rows = gf.guideline_facts(
con, object(), FAM, ask=ask_with([(1, "Made up words appear.")]),
log=RunLog(tmp_path / "l.jsonl"),
) # fmt: skip
(row,) = _by(rows, fact="panel_action")
assert row.extractor == "cpt-panel" and row.code == "70001-70003"
assert row.value.startswith("Deleted codes 70003; revised codes 70001, 70002")
assert row.cite_locator == "tab 10, PDF p. 2"
def test_pages_collapse_to_a_range():
assert gf._pages(["p. 9", "p. 9"]) == "p. 9"
assert gf._pages(["p. 10", "p. 9"]) == "p. 9, p. 10"
assert gf._pages(["p. 37", "p. 38", "p. 40"]) == "pp. 37–40"
assert (
gf._pages(["p. 3", "Chap > Zed", "p. 4", "p. 5"])
== "p. 3, p. 4, p. 5, Chap > Zed"
)

View File

@@ -139,7 +139,7 @@ CODING_PARA = (
ALIAS_PARA = (
"We are proposing that prolonged home or residence services would be reportable "
"under GXXX3 ( Prolonged home or residence evaluation and management service(s) "
"beyond the total time for the primary service; each additional 15 minutes "
"beyond the total time for the primary service; each extra 15 minutes "
"(list separately in addition to CPT codes 99345, 99350 for home or residence "
"evaluation and management services). (Do not report GXXX3 on the same date "
"as 99358))."
@@ -186,7 +186,7 @@ def test_docket_events_cy2023_home_visits(con, home_store):
write_rounds(con, "HOME-VISITS", [_round(), _round(year=2008)])
write_events(con, "99342", [_event("99342", 2023, "cpt_panel")])
fam = _fam(key)
got = docket_events(con, fam, 2023, store)
got = docket_events(con, fam, 2023, store, guidelines=False)
assert [e.event_key for e in got] == [
"HOME-VISITS:2023:valuation",
"HOME-VISITS:2023:coding",
@@ -218,7 +218,9 @@ def test_docket_events_cy2023_home_visits(con, home_store):
)
assert "[\u00b6880]" in g
assert "99341" in other and "other codes or services are not given" in other
assert docket_events(con, fam, 2023, store) == got # deterministic
assert (
docket_events(con, fam, 2023, store, guidelines=False) == got
) # deterministic
def test_docket_events_without_store_uses_lineage_only(con):
@@ -257,13 +259,13 @@ def test_telehealth_paragraph_with_a_range_and_item_fallback(con):
2: "Telehealth for something else, 12345.",
},
)
got = docket_events(con, FAM, 2024, s)
got = docket_events(con, FAM, 2024, s, guidelines=False)
assert [e.event_key.split(":")[-1] for e in got] == ["telehealth", "other"]
assert "99324-99328" in got[0].text
s.close()
s2, _ = _store("CY 2024 Payment Policies; PFS", {1: "Telehealth for 12345."})
assert len(docket_events(con, FAM, 2024, s2)) == 1
assert len(docket_events(con, FAM, 2030, s2)) == 1
assert len(docket_events(con, FAM, 2024, s2, guidelines=False)) == 1
assert len(docket_events(con, FAM, 2030, s2, guidelines=False)) == 1
s2.close()
@@ -317,8 +319,8 @@ def test_stance_schema(events):
assert item["properties"]["reason"]["maxLength"] == 200
assert item["properties"]["evidence"]["maxLength"] == 200
assert PROMPT_VERSIONS == {
"multi": "stance-v4",
"per-event": "stance-v4-per-event",
"multi": "stance-v5",
"per-event": "stance-v5-per-event",
}
assert STANCE_PROMPT_VERSION == PROMPT_VERSIONS[DEFAULT_METHOD]
@@ -369,7 +371,7 @@ def test_rows_carry_fields(events):
"support",
"likes increase",
"We support the proposed increase in work RVUs for CPT code 99342",
"model:qwen-test@stance-v4",
"model:qwen-test@stance-v5",
)
]
@@ -766,7 +768,7 @@ def test_paragraph_choice_is_by_density_and_names_the_family(con):
6: "Telehealth for 99345 too " + "w " * 40,
},
)
tele = _by_slug(docket_events(con, FAM, 2023, s), "telehealth")
tele = _by_slug(docket_events(con, FAM, 2023, s, guidelines=False), "telehealth")
assert tele.index("[¶2]") < tele.index("[¶3]")
assert tele.count("[¶") == 2 # at most two paragraphs
assert "[¶4]" not in tele and "[¶5]" not in tele
@@ -782,18 +784,18 @@ def test_time_counts_a_quarter_of_the_guideline_words(con):
3: "Deleted code 99343 is gone.",
},
)
coding = _by_slug(docket_events(con, FAM, 2023, s), "coding")
coding = _by_slug(docket_events(con, FAM, 2023, s, guidelines=False), "coding")
assert coding.index("[¶3]") < coding.index("[¶2]")
assert coding.count("[¶") == 2 and "[¶1]" not in coding
s.close()
def test_coding_event_from_paragraphs_alone(con):
def test_coding_event_from_paragraphs_alone_is_v4_only(con):
s, _ = _store(
"CY 2030 Payment Policies Under the Physician Fee Schedule; Proposed Rule",
{1: "New guideline for 99341 visits."},
)
ev = docket_events(con, FAM, 2030, s)
ev = docket_events(con, FAM, 2030, s, guidelines=False)
assert ev[0].event_key.endswith(":coding")
assert ev[0].text.startswith("Coding changes. Rule text: [¶1]")
s.close()
@@ -835,7 +837,7 @@ def test_per_event_asks_once_per_item_and_event(tmp_path, events):
(events[0].event_key, "support"),
(events[2].event_key, "modify"),
]
assert rows[0].extractor == "model:qwen-test@stance-v4-per-event"
assert rows[0].extractor == "model:qwen-test@stance-v5-per-event"
# the focused prompt names only its own event
system = ask.calls[1][0]
assert events[1].event_key in system and events[0].event_key not in system
@@ -844,7 +846,7 @@ def test_per_event_asks_once_per_item_and_event(tmp_path, events):
json.loads(x) for x in (tmp_path / "stance.jsonl").read_text().splitlines()
]
assert {e["unit"] for e in ledger} == {f"K1::{e.event_key}" for e in events}
assert {e["version"] for e in ledger} == {"stance-v4-per-event"}
assert {e["version"] for e in ledger} == {"stance-v5-per-event"}
# replay without a model reads the same rows
(again, c2), _ = _run(
tmp_path, None, [_commenter("K1")], {"K1": TEXT}, events,
@@ -1222,3 +1224,284 @@ def test_stances_for_applies_subjects(tmp_path, events):
)
assert rows == [] # same ledger entry, replayed through a different filter
assert len(ask.calls) == 1
# ── stance-v5: guideline facts, coding event rule, link kinds (R69, R74) ──
def _gf(code, year, fact, value, loc="p. 9"):
from pfs.codetables import GuidelineFactRow
return GuidelineFactRow(
"HOME-VISITS", code, year, fact, value, "B", loc, "cpt-book"
)
V5_FACTS = [
_gf("99341", 2022, "selection_basis", "history_exam_mdm"),
_gf("99341", 2024, "selection_basis", "mdm_or_time"),
_gf("99341", 2024, "time_threshold_min", "15"),
_gf("99343", 2024, "deleted_in_edition", "2022"),
_gf("99341-99350", 2024, "scope_point", "Care is at the residence.", "p. 28"),
]
def test_generations_and_versions():
from pfs.stance import GENERATIONS, guideline_text, prompt_version
assert GENERATIONS == ("stance-v4", "stance-v5", "stance-v6")
assert prompt_version("multi", "stance-v5") == "stance-v5"
assert prompt_version("per-event", "stance-v5") == "stance-v5-per-event"
assert prompt_version("multi", "stance-v4") == "stance-v4"
assert guideline_text("stance-v5") and not guideline_text("stance-v4")
def test_v5_coding_event_states_cpt_facts(con):
from pfs.codetables import write_guideline_facts
write_guideline_facts(con, "HOME-VISITS", V5_FACTS)
ev = docket_events(con, FAM, 2023, guidelines=True)
coding = _by_slug(ev, "coding")
assert "CPT books on file, 2022 and 2024" in coding
assert (
"99341 is selected by level of medical decision making or total time" in coding
)
assert "total-time thresholds 99341 15 minutes" in coding
assert "Care is at the residence. (CPT 2024, p. 28)" in coding
# v4 behaviour is unchanged: no facts text
assert "CPT books" not in " ".join(
e.text for e in docket_events(con, FAM, 2023, guidelines=False)
)
def test_v5_coding_event_needs_facts_not_keywords(con):
s, _ = _store(
"CY 2030 Payment Policies Under the Physician Fee Schedule; Proposed Rule",
{1: "New guideline for 99341 visits."},
)
# keywords alone: v4 makes an event, v5 does not
assert [
e.event_key.rsplit(":", 1)[-1]
for e in docket_events(con, FAM, 2030, s, guidelines=True)
] == ["other"]
assert docket_events(con, FAM, 2030, s, guidelines=False)[0].event_key.endswith(
":coding"
)
# a lineage event that year makes one, and cites the paragraph too
write_events(con, "99342", [_event("99342", 2030, "created")])
ev = docket_events(con, FAM, 2030, s, guidelines=True)
assert ev[0].event_key.endswith(":coding")
assert "1 created" in ev[0].text and "[¶1]" in ev[0].text
s.close()
def test_v5_coding_event_from_facts_alone(con):
from pfs.codetables import write_guideline_facts
write_guideline_facts(con, "HOME-VISITS", V5_FACTS[:2])
ev = docket_events(con, FAM, 2023, guidelines=True)
assert ev[0].event_key.endswith(":coding")
assert "CPT books on file, 2022 and 2024" in ev[0].text
def test_facts_table_missing_is_tolerated(con):
con.execute("DROP TABLE pfs.code_guideline_fact")
got = [
e.event_key.rsplit(":", 1)[-1]
for e in docket_events(con, FAM, 2030, guidelines=True)
]
assert got == ["other"]
def test_missing_facts_error_other_than_table_propagates(con, monkeypatch):
import pfs.stance as st
def boom(c, f):
raise RuntimeError("disk gone")
monkeypatch.setattr(st, "read_guideline_facts", boom)
with pytest.raises(RuntimeError):
docket_events(con, FAM, 2023, guidelines=True)
def test_link_relevance_words_depend_on_kind():
from pfs.stance import event_subjects
fam = dataclasses.replace(
FAM,
links=tuple(ln for ln in FAM.links if ln.target in ("G2211", "B1", "G0318")),
)
evs = [
EventChoice(f"HOME-VISITS:2026:{s}", s, 2026) for s in ("G2211", "B1", "G0318")
]
sub = event_subjects(fam, evs, by_kind=True)
g2211, b1, g0318 = (sub[e.event_key] for e in evs)
assert g2211.named_in("G2211 applies to home or residence visits")
assert g2211.named_in("the add-on for home or residence visits")
assert g2211.named_in("longitudinal home visit codes")
assert g2211.named_in("visit complexity in the home visit codes")
assert not g2211.named_in("prolonged home or residence visit time")
assert b1.named_in("the modifier for home or residence visits")
assert b1.named_in("B1 for 99341")
assert not b1.named_in("prolonged home or residence visit time")
assert g0318.named_in("prolonged home or residence visit time")
assert not g0318.named_in("the add-on for home or residence visits")
# v4 used "prolonged" for every link
old = event_subjects(fam, evs, by_kind=False)
assert old[evs[0].event_key].named_in("prolonged home or residence visit time")
# the shipped default follows the shipped generation
from pfs.stance import guideline_text
dflt = event_subjects(fam, evs)
assert (
dflt[evs[0].event_key].named_in("prolonged home visit codes")
!= guideline_text()
)
# ── stance-v6: telehealth needs lineage, paragraph order, sentence cuts (R78) ──
def test_v6_generation_flags():
from pfs.stance import fixed_text, guideline_text
assert guideline_text("stance-v6") and guideline_text("stance-v5")
assert fixed_text("stance-v6") and not fixed_text("stance-v5")
assert not fixed_text("stance-v4")
def test_v6_telehealth_event_needs_lineage_not_a_paragraph(con):
s, _ = _store(
"CY 2030 Payment Policies Under the Physician Fee Schedule; Proposed Rule",
{1: "We add 99341 as a base code billed with GADV1 to the telehealth list."},
)
slugs = lambda evs: [e.event_key.rsplit(":", 1)[-1] for e in evs] # noqa: E731
assert "telehealth" not in slugs(
docket_events(con, FAM, 2030, s, guidelines=True, fixed=True)
)
assert "telehealth" in slugs(
docket_events(con, FAM, 2030, s, guidelines=False, fixed=False)
)
# a lineage telehealth_list event for a family code makes one
write_events(con, "99342", [_event("99342", 2030, "telehealth_list")])
ev = docket_events(con, FAM, 2030, s, guidelines=True, fixed=True)
assert "(lineage: telehealth list change for 99342)" in _by_slug(ev, "telehealth")
s.close()
def test_v6_telehealth_event_for_a_link_offered_that_year(con):
write_events(con, "G0318", [_event("G0318", 2023, "telehealth_list")])
ev = docket_events(con, FAM, 2023, guidelines=True, fixed=True)
assert "telehealth" in [e.event_key.rsplit(":", 1)[-1] for e in ev]
# a link not offered that year does not count
write_events(con, "G2211", [_event("G2211", 2023, "telehealth_list")])
con.execute("DELETE FROM pfs.code_event WHERE code = 'G0318'")
ev = docket_events(con, FAM, 2023, guidelines=True, fixed=True)
assert "telehealth" not in [e.event_key.rsplit(":", 1)[-1] for e in ev]
LONG_A = (
"Zed is new for 99341. "
+ "Filler words continue here. " * 12
+ "The guideline for 99341 changed."
)
def test_v6_paragraphs_in_pid_order_cut_at_sentences(con):
long_p = (
"The guideline for 99342 changed today. "
+ "Quux filler sentence goes on. " * 30
)
s, _ = _store(
"CY 2030 Payment Policies Under the Physician Fee Schedule; Proposed Rule",
{
5: "The guideline for 99341 and the guideline for 99341 changed again.",
9: "Deleted guideline for 99343 deleted.",
12: long_p,
},
)
write_events(con, "99342", [_event("99342", 2030, "created")])
coding = _by_slug(
docket_events(con, FAM, 2030, s, guidelines=True, fixed=True), "coding"
)
assert coding.index("[¶5]") < coding.index("[¶9]") # p_id order, not density
assert "[¶12]" not in coding # only two paragraphs
old = _by_slug(
docket_events(con, FAM, 2030, s, guidelines=False, fixed=False), "coding"
)
assert old.index("[¶9]") < old.index("[¶5]") # v4: densest first
s.close()
def test_excerpt_sentences_never_cut_mid_sentence():
from pfs.stance import _CODING_WORDS, _excerpt
text = "First sentence about the guideline. " + "Plain filler sentence here. " * 30
out = _excerpt(text, _CODING_WORDS, sentences=True)
assert out.endswith(".") and len(out) <= 600
assert out.startswith("First sentence about the guideline.")
# the run with the most hits wins
text2 = (
"Plain filler sentence here. " * 25
+ "The guideline guideline guideline text ends here."
)
assert _excerpt(text2, _CODING_WORDS, sentences=True).endswith("text ends here.")
# a short paragraph is whole
assert _excerpt("Short one.", _CODING_WORDS, sentences=True) == "Short one."
# a single sentence longer than the limit is cut at a word
one = "guideline " * 100
assert len(_excerpt(one, _CODING_WORDS, sentences=True)) <= 600
# ── multi-docket golden files (R78d) ─────────────────────────────────
def test_golden_dockets_single_and_multi():
from pfs.stance import golden_dockets, item_dockets
single = {"family": "F", "docket": "D1", "items": [{"item_key": "K1", "cells": {}}]}
assert golden_dockets(single) == ["D1"] and item_dockets(single) == {"K1": "D1"}
multi = {
"family": "F",
"dockets": ["D1", "D2"],
"items": [
{"item_key": "K1", "docket": "D1"},
{"item_key": "K2", "docket": "D2"},
],
}
assert golden_dockets(multi) == ["D1", "D2"]
assert item_dockets(multi) == {"K1": "D1", "K2": "D2"}
bad = {**multi, "items": [{"item_key": "K3"}]}
with pytest.raises(ValueError, match="K3"):
item_dockets(bad)
bad = {**multi, "items": [{"item_key": "K3", "docket": "D9"}]}
with pytest.raises(ValueError, match="D9"):
item_dockets(bad)
def test_eval_record_names_every_docket():
from pfs.stance import eval_record, score
golden = {
"family": "F",
"dockets": ["D1", "D2"],
"items": [
{
"item_key": "K1",
"docket": "D1",
"cells": {"F:2023:x": {"label": "support"}},
},
{
"item_key": "K2",
"docket": "D2",
"cells": {"F:2026:x": {"label": "oppose"}},
},
],
}
rows = [
StanceRow("F", "K1", "D1", "F:2023:x", "support", "", "", "m"),
StanceRow("F", "K2", "D2", "F:2026:x", "oppose", "", "", "m"),
]
rec = eval_record(golden, score(golden, rows))
assert rec["dockets"] == ["D1", "D2"] and rec["docket"] == "D1; D2"
assert (rec["recall"], rec["direction"], rec["n_items"]) == (1.0, 1.0, 2)

View File

@@ -136,6 +136,18 @@ def test_epub_pages_split_on_page_spans(tmp_path):
]
def test_epub_pages_split_on_page_anchors(tmp_path):
"""The 2022 CPT Professional EPUB marks pages with ``<a id="page_N"/>``."""
path = tmp_path / "book.epub"
_paged_epub(
path,
'<html><body><div><a id="page_5"/><b>Title</b></div><p>Five.</p>'
'<a id="page_6"></a><p>Six.</p><a href="x.xhtml#page_7">7</a></body></html>',
"<html><body><p>Six more.</p></body></html>",
)
assert [label for label, _ in epub_pages(path)] == ["5", "6"]
def test_epub_pages_without_container_sorts_members(tmp_path):
path = tmp_path / "book.epub"
_paged_epub(