From 07a0f32afec3fba18c8ec65e71abdf1bec70aedc Mon Sep 17 00:00:00 2001 From: kert Date: Sat, 31 Oct 2026 20:08:18 -0400 Subject: [PATCH] feat(lead): add the LEAD target registry --- src/cli/__init__.py | 2 + src/cli/lead.py | 16 +++++ src/lead/targets.py | 109 +++++++++++++++++++++++++++++ tests/lead/test_targets.py | 137 +++++++++++++++++++++++++++++++++++++ 4 files changed, 264 insertions(+) create mode 100644 src/cli/lead.py create mode 100644 src/lead/targets.py create mode 100644 tests/lead/test_targets.py diff --git a/src/cli/__init__.py b/src/cli/__init__.py index 3ead03e..746c8f7 100644 --- a/src/cli/__init__.py +++ b/src/cli/__init__.py @@ -22,6 +22,7 @@ from cli.docs import app as docs_app from cli.generate import app as generate_app from cli.health import health from cli.lake import app as lake_app +from cli.lead import app as lead_app from cli.llm import app as llm_app from cli.load import app as load_app from cli.mail import app as mail_app @@ -60,6 +61,7 @@ app.add_typer( help="CMS rulemaking comment text extraction & analysis.", ) app.add_typer(lake_app, name="lake", help="Lakehouse schema and data.") +app.add_typer(lead_app, name="lead", help="LEAD target registry and evidence ledger.") app.add_typer(llm_app, name="llm", help="Local RAG — index, search, tag.") app.add_typer(db_app, name="db", help="DuckDB utilities.") app.add_typer(docs_app, name="docs", help="Documentation generation.") diff --git a/src/cli/lead.py b/src/cli/lead.py new file mode 100644 index 0000000..d3769c7 --- /dev/null +++ b/src/cli/lead.py @@ -0,0 +1,16 @@ +"""stack lead — target registry and evidence ledger.""" + +from __future__ import annotations + +import typer + +from lead.targets import TARGETS + +app = typer.Typer(no_args_is_help=True) + + +@app.command(name="targets") +def targets() -> None: + """Print every target ID, family, and name.""" + for target in TARGETS: + typer.echo(f"{target.id}\t{target.family}\t{target.name}") diff --git a/src/lead/targets.py b/src/lead/targets.py new file mode 100644 index 0000000..7b90dcb --- /dev/null +++ b/src/lead/targets.py @@ -0,0 +1,109 @@ +"""IDs for everything the LEAD methodology scores. + +Claims, features, runs, and limits refer to these IDs. The set is the +one in the evidence-chassis spec, including the benchmark components +that already have a function in :mod:`lead.benchmark` or +:mod:`lead.settlement`. +""" + +from __future__ import annotations + +from dataclasses import dataclass + + +@dataclass(frozen=True) +class Target: + """One scored component.""" + + id: str + family: str + name: str + + +def _row(family: str, rows: tuple[tuple[str, str], ...]) -> tuple[Target, ...]: + return tuple(Target(id=i, family=family, name=n) for i, n in rows) + + +TARGETS: tuple[Target, ...] = ( + *_row( + "quality", + ( + ("Q.ACR", "ACR"), + ("Q.UAMCC", "UAMCC"), + ("Q.DAH", "DAH"), + ("Q.TFU", "TFU"), + ("Q.CAHPS", "CAHPS"), + ("Q.CBP", "CBP"), + ("Q.GSD", "GSD"), + ), + ), + *_row( + "high_needs", + ( + ("HN.1", "mobility-impairment diagnosis"), + ("HN.2", "hospital bed or transfer-equipment DME claim"), + ("HN.3", "Kim claims-based frailty index"), + ("HN.4", "A&D risk score ≥ 3.0"), + ("HN.5", "ESRD risk score ≥ 0.35"), + ( + "HN.6", + "A&D 2.0–3.0 or ESRD 0.24–0.35 plus ≥ 2 unplanned admissions", + ), + ("HN.7", "≥ 45 covered SNF days"), + ), + ), + *_row( + "risk", + ( + ("RA.PROSP", "non-High Needs A&D"), + ("RA.CONC", "High Needs concurrent"), + ("RA.ESRD", "ESRD"), + ("RA.NORM", "normalization"), + ("RA.CI", "coding intensity"), + ("RA.CAP", "4% High Needs growth cap"), + ("RA.SAHS", "anomalous-billing and skin-substitute mitigation"), + ), + ), + *_row( + "benchmark", + ( + ("BM.HISTORICAL", "historical_benchmark"), + ("BM.VOLUNTARY_GUARDRAIL", "voluntary_guardrail"), + ("BM.REGIONAL", "regional_ffs_expenditure"), + ("BM.SPENDING_DESIGNATION", "spending_designation"), + ("BM.ADJ_CAP", "benchmark_adjustment_cap"), + ("BM.REGIONAL_EFFICIENCY", "regional_efficiency_adjustment"), + ("BM.PRIOR_SAVINGS", "prior_savings_adjustment"), + ("BM.PY", "performance_year_benchmark_pbpm"), + ("BM.DISCOUNT", "apply_discount"), + ("BM.QUALITY_WITHHOLD", "quality_withhold"), + ("BM.QUALITY_EARN_BACK", "quality_earn_back"), + ("BM.RETENTION", "retention_incentive_adjustment"), + ("BM.GROSS", "gross_savings_losses"), + ("BM.SHARED", "shared_savings_losses"), + ("BM.SEQUESTRATION", "sequestration_amount"), + ), + ), +) + +_BY_ID = {t.id: t for t in TARGETS} + + +def by_id(target_id: str) -> Target: + """Return the target with this ID. + + Raises: + KeyError: the ID is not in the registry. + """ + try: + return _BY_ID[target_id] + except KeyError: + raise KeyError(target_id) from None + + +def families() -> dict[str, tuple[Target, ...]]: + """Targets grouped by family, in registry order.""" + out: dict[str, list[Target]] = {} + for target in TARGETS: + out.setdefault(target.family, []).append(target) + return {family: tuple(rows) for family, rows in out.items()} diff --git a/tests/lead/test_targets.py b/tests/lead/test_targets.py new file mode 100644 index 0000000..268dfba --- /dev/null +++ b/tests/lead/test_targets.py @@ -0,0 +1,137 @@ +"""The LEAD target registry matches the spec's IDs.""" + +from __future__ import annotations + +import pytest +from typer.testing import CliRunner + +from cli import app +from lead.targets import TARGETS, by_id + +runner = CliRunner() + +EXPECTED_IDS = { + "Q.ACR", + "Q.UAMCC", + "Q.DAH", + "Q.TFU", + "Q.CAHPS", + "Q.CBP", + "Q.GSD", + "HN.1", + "HN.2", + "HN.3", + "HN.4", + "HN.5", + "HN.6", + "HN.7", + "RA.PROSP", + "RA.CONC", + "RA.ESRD", + "RA.NORM", + "RA.CI", + "RA.CAP", + "RA.SAHS", + "BM.HISTORICAL", + "BM.VOLUNTARY_GUARDRAIL", + "BM.REGIONAL", + "BM.SPENDING_DESIGNATION", + "BM.ADJ_CAP", + "BM.REGIONAL_EFFICIENCY", + "BM.PRIOR_SAVINGS", + "BM.PY", + "BM.DISCOUNT", + "BM.QUALITY_WITHHOLD", + "BM.QUALITY_EARN_BACK", + "BM.RETENTION", + "BM.GROSS", + "BM.SHARED", + "BM.SEQUESTRATION", +} + +NAMES = { + "HN.1": "mobility-impairment diagnosis", + "HN.2": "hospital bed or transfer-equipment DME claim", + "HN.3": "Kim claims-based frailty index", + "HN.4": "A&D risk score ≥ 3.0", + "HN.5": "ESRD risk score ≥ 0.35", + "HN.6": "A&D 2.0–3.0 or ESRD 0.24–0.35 plus ≥ 2 unplanned admissions", + "HN.7": "≥ 45 covered SNF days", + "RA.PROSP": "non-High Needs A&D", + "RA.CONC": "High Needs concurrent", + "RA.CAP": "4% High Needs growth cap", + "RA.SAHS": "anomalous-billing and skin-substitute mitigation", + "BM.HISTORICAL": "historical_benchmark", + "BM.VOLUNTARY_GUARDRAIL": "voluntary_guardrail", + "BM.REGIONAL": "regional_ffs_expenditure", + "BM.SPENDING_DESIGNATION": "spending_designation", + "BM.ADJ_CAP": "benchmark_adjustment_cap", + "BM.REGIONAL_EFFICIENCY": "regional_efficiency_adjustment", + "BM.PRIOR_SAVINGS": "prior_savings_adjustment", + "BM.PY": "performance_year_benchmark_pbpm", + "BM.DISCOUNT": "apply_discount", + "BM.QUALITY_WITHHOLD": "quality_withhold", + "BM.QUALITY_EARN_BACK": "quality_earn_back", + "BM.RETENTION": "retention_incentive_adjustment", + "BM.GROSS": "gross_savings_losses", + "BM.SHARED": "shared_savings_losses", + "BM.SEQUESTRATION": "sequestration_amount", +} + + +def test_registry_matches_the_spec(): + assert {t.id for t in TARGETS} == EXPECTED_IDS + assert [t.id for t in TARGETS] == [ + "Q.ACR", + "Q.UAMCC", + "Q.DAH", + "Q.TFU", + "Q.CAHPS", + "Q.CBP", + "Q.GSD", + "HN.1", + "HN.2", + "HN.3", + "HN.4", + "HN.5", + "HN.6", + "HN.7", + "RA.PROSP", + "RA.CONC", + "RA.ESRD", + "RA.NORM", + "RA.CI", + "RA.CAP", + "RA.SAHS", + "BM.HISTORICAL", + "BM.VOLUNTARY_GUARDRAIL", + "BM.REGIONAL", + "BM.SPENDING_DESIGNATION", + "BM.ADJ_CAP", + "BM.REGIONAL_EFFICIENCY", + "BM.PRIOR_SAVINGS", + "BM.PY", + "BM.DISCOUNT", + "BM.QUALITY_WITHHOLD", + "BM.QUALITY_EARN_BACK", + "BM.RETENTION", + "BM.GROSS", + "BM.SHARED", + "BM.SEQUESTRATION", + ] + assert by_id("HN.3").name.startswith("Kim") + assert by_id("Q.ACR").family == "quality" + for target_id, name in NAMES.items(): + assert by_id(target_id).name == name + + +def test_unknown_target_raises(): + with pytest.raises(KeyError): + by_id("nope") + + +def test_targets_command_lists_the_registry(): + result = runner.invoke(app, ["lead", "targets"]) + assert result.exit_code == 0 + assert "HN.3" in result.stdout + assert "BM.SEQUESTRATION" in result.stdout