homelab/stack
1
0
Fork 0
Code Issues 131 Pull Requests 1 Actions Packages Projects 1 Releases Wiki Activity

feat(lead): add the LEAD target registry

Browse Source
This commit is contained in:
kert
2026-10-31 20:08:18 -04:00
parent 6634109484
commit 07a0f32afe
4 changed files with 264 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
src/cli/__init__.py
View File

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

16
src/cli/lead.py Normal file
View File

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

109
src/lead/targets.py Normal file
View File

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

137
tests/lead/test_targets.py Normal file
View File

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