diff --git a/src/cli/pfs.py b/src/cli/pfs.py index 8c75f1d..9b13756 100644 --- a/src/cli/pfs.py +++ b/src/cli/pfs.py @@ -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']}, " diff --git a/src/pfs/codetables.py b/src/pfs/codetables.py index 03a289f..7b04f40 100644 --- a/src/pfs/codetables.py +++ b/src/pfs/codetables.py @@ -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]) diff --git a/src/pfs/curated.yaml b/src/pfs/curated.yaml index b33728e..6a6d69f 100644 --- a/src/pfs/curated.yaml +++ b/src/pfs/curated.yaml @@ -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}} diff --git a/src/pfs/guideline_facts.py b/src/pfs/guideline_facts.py new file mode 100644 index 0000000..c4a45e9 --- /dev/null +++ b/src/pfs/guideline_facts.py @@ -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"(? 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 diff --git a/src/pfs/stance.py b/src/pfs/stance.py index a6d9105..6df04e7 100644 --- a/src/pfs/stance.py +++ b/src/pfs/stance.py @@ -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} diff --git a/src/rex/comments/epub_text.py b/src/rex/comments/epub_text.py index 19808bd..6cc1fe7 100644 --- a/src/rex/comments/epub_text.py +++ b/src/rex/comments/epub_text.py @@ -137,8 +137,9 @@ def extract_text(path: str | Path) -> str: #: the AMA books mark each printed page with an empty ```` +#: (the 2022 Professional edition uses ````) #: (labels are roman numerals for front matter, arabic after) -_PAGE_SPAN = re.compile(r'|>)') +_PAGE_SPAN = re.compile(r'<(?:span|a) id="page_([^"\x00]*)"\s*(?:/>|>(?:span|a)>)') _PAGE_MARK = re.compile(r"\x00([^\x00]*)\x00") diff --git a/tests/cli/test_pfs_cli.py b/tests/cli/test_pfs_cli.py index 97c58db..7f585c3 100644 --- a/tests/cli/test_pfs_cli.py +++ b/tests/cli/test_pfs_cli.py @@ -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 diff --git a/tests/pfs/test_guideline_facts.py b/tests/pfs/test_guideline_facts.py new file mode 100644 index 0000000..3e7f663 --- /dev/null +++ b/tests/pfs/test_guideline_facts.py @@ -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" + ) diff --git a/tests/pfs/test_stance.py b/tests/pfs/test_stance.py index 012c664..cd714c5 100644 --- a/tests/pfs/test_stance.py +++ b/tests/pfs/test_stance.py @@ -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) diff --git a/tests/rex/comments/test_epub_text.py b/tests/rex/comments/test_epub_text.py index 48310c3..c661c8e 100644 --- a/tests/rex/comments/test_epub_text.py +++ b/tests/rex/comments/test_epub_text.py @@ -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 ````.""" + path = tmp_path / "book.epub" + _paged_epub( + path, + '
Five.
' + 'Six.
7', + "Six more.
", + ) + 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(