pdpcompare 1.0.0__py3-none-any.whl

pdpcompare/bundle.py

@@ -0,0 +1,136 @@
+"""Wire contract for the remote plan-data API (spec §4). Shared by the
+desk's RemoteSource and the server's bundle builder — this module is the
+single source of truth for the request/response shape. Pure data: no I/O,
+no SQL, no httpx. Data minimization: requests carry RXCUIs/NDCs only,
+never drug names or quantities."""
+from __future__ import annotations
+from dataclasses import asdict, dataclass
+
+
+@dataclass(frozen=True)
+class DrugQuery:
+    candidate_rxcuis: tuple[str, ...]
+    ndcs: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class BundleRequest:
+    plan_year: int
+    zip: str
+    drugs: tuple[DrugQuery, ...]
+    pharmacy_npi: str | None
+    pharmacy_zip: str | None
+
+    def to_dict(self) -> dict:
+        return {"plan_year": self.plan_year, "zip": self.zip,
+                "drugs": [{"candidate_rxcuis": list(d.candidate_rxcuis),
+                           "ndcs": list(d.ndcs)} for d in self.drugs],
+                "pharmacy": {"npi": self.pharmacy_npi,
+                             "zip": self.pharmacy_zip}}
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "BundleRequest":
+        return cls(plan_year=int(d["plan_year"]), zip=str(d["zip"]),
+                   drugs=tuple(DrugQuery(
+                       candidate_rxcuis=tuple(x["candidate_rxcuis"]),
+                       ndcs=tuple(x["ndcs"])) for x in d["drugs"]),
+                   pharmacy_npi=d["pharmacy"].get("npi"),
+                   pharmacy_zip=d["pharmacy"].get("zip"))
+
+
+@dataclass(frozen=True)
+class InsulinCostRow:
+    """Retail insulin cost-sharing for one tier (30-day code '1'). Raw file
+    values: copay in dollars, coinsurance as a FRACTION — decoding to
+    costsim's percent semantics happens desk-side via
+    plandata.decode_insulin_share, the same code path local mode uses.
+
+    tier None = wildcard row (CMS '.') applying to every tier; an
+    exact-tier row takes precedence desk-side."""
+    tier: int | None
+    copay_pref: float | None
+    copay_nonpref: float | None
+    coin_pref: float | None
+    coin_nonpref: float | None
+
+
+@dataclass(frozen=True)
+class BundlePlan:
+    contract_id: str
+    plan_id: str
+    segment_id: str
+    plan_name: str
+    formulary_id: str
+    deductible: float | None
+    monthly_premium: float | None
+    # preferred | standard | out_of_network | preferred_out_of_area |
+    # standard_out_of_area
+    pharmacy_status: str
+    insulin_costs: tuple[InsulinCostRow, ...]
+
+
+@dataclass(frozen=True)
+class CoverageRow:
+    formulary_id: str
+    rxcui: str
+    tier: int
+    prior_auth: bool
+    quantity_limit: bool
+    step_therapy: bool
+    ndc: str | None         # the formulary's CMS proxy NDC
+
+
+@dataclass(frozen=True)
+class UnitCostRow:
+    contract_id: str
+    plan_id: str
+    segment_id: str
+    ndc: str
+    unit_cost: float
+
+
+@dataclass(frozen=True)
+class CostShareRow:
+    contract_id: str
+    plan_id: str
+    segment_id: str
+    tier: int
+    preferred: bool
+    cost_type: str          # "copay" | "coinsurance" (already decoded)
+    cost_amt: float         # dollars, or percent 0-100 for coinsurance
+    ded_applies: bool
+
+
+@dataclass(frozen=True)
+class Bundle:
+    plan_year: int
+    premiums_plan_year: int | None
+    loaded_at: str | None
+    plans: tuple[BundlePlan, ...]
+    coverage: tuple[CoverageRow, ...]
+    unit_costs: tuple[UnitCostRow, ...]
+    cost_shares: tuple[CostShareRow, ...]
+
+    def to_dict(self) -> dict:
+        return {"plan_year": self.plan_year,
+                "premiums_plan_year": self.premiums_plan_year,
+                "loaded_at": self.loaded_at,
+                "plans": [asdict(p) for p in self.plans],
+                "coverage": [asdict(c) for c in self.coverage],
+                "unit_costs": [asdict(u) for u in self.unit_costs],
+                "cost_shares": [asdict(s) for s in self.cost_shares]}
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "Bundle":
+        pp = d.get("premiums_plan_year")
+        return cls(plan_year=int(d["plan_year"]),
+                   premiums_plan_year=int(pp) if pp is not None else None,
+                   loaded_at=d.get("loaded_at"),
+                   plans=tuple(BundlePlan(**{
+                       **p, "insulin_costs": tuple(
+                           InsulinCostRow(**r) for r in p["insulin_costs"])})
+                       for p in d["plans"]),
+                   coverage=tuple(CoverageRow(**c) for c in d["coverage"]),
+                   unit_costs=tuple(UnitCostRow(**u) for u in d["unit_costs"]),
+                   cost_shares=tuple(CostShareRow(**s)
+                                     for s in d["cost_shares"]))

pdpcompare/cli.py

@@ -0,0 +1,273 @@
+"""Command-line entry point. The Claude skill drives these commands."""
+from __future__ import annotations
+import argparse, json, os, sys
+from pathlib import Path
+import httpx
+from . import (clientstore, config, db, deskupdate, doctor, engine, inputs,
+              plandata, recommend, sources)
+from .ingest import catalog, geo_loader, landscape_loader, spuf_loader
+from .outputs import letter, worksheet
+from .rxnorm import RxNormClient
+
+def _connect():
+    return db.connect()
+
+def _rx_client():
+    return RxNormClient(cache_dir=config.CACHE_DIR)
+
+def _table_exists(conn, name: str) -> bool:
+    return conn.execute(
+        "SELECT count(*) FROM information_schema.tables WHERE table_name = ?",
+        [name]).fetchone()[0] > 0
+
+def _build_source(args):
+    """Remote mode when --api-url (or PDPCOMPARE_API_URL) is set;
+    otherwise local DuckDB, exactly as before. Loud fail, no silent
+    fallback between modes (spec §7)."""
+    if args.api_url:
+        if not args.api_key:
+            print("ERROR: --api-key (or PDPCOMPARE_API_KEY) is required "
+                  "with --api-url", file=sys.stderr)
+            return None
+        return sources.RemoteSource(args.api_url, args.api_key)
+    return sources.LocalSource(_connect())
+
+def cmd_ingest(args) -> int:
+    if args.landscape and not Path(args.landscape).is_file():
+        # Fail fast — before any multi-GB SPUF/GeoNames download.
+        print(f"ERROR: Landscape CSV not found: {args.landscape}",
+              file=sys.stderr)
+        return 1
+    conn = _connect()
+    if args.spuf_dir:
+        extract_dir = Path(args.spuf_dir)
+    else:
+        rel = catalog.latest_spuf()
+        print(f"Downloading {rel.title} ({rel.modified})…", file=sys.stderr)
+        extract_dir = catalog.download_and_extract(rel.url, config.CACHE_DIR / "spuf")
+    spuf_loader.load_spuf(
+        conn, extract_dir, plan_year=args.year,
+        overrides=spuf_loader.load_overrides(config.OVERRIDES_PATH))
+    txt = geo_loader.download_geonames(config.CACHE_DIR / "geo")
+    geo_loader.load_geonames(conn, txt)
+    if args.landscape:
+        # Optional override: premiums already came from the SPUF above —
+        # this replaces them with the annual Landscape file. (Deductibles
+        # always stay SPUF-derived; the override only touches premiums.)
+        landscape_loader.load_landscape(conn, Path(args.landscape),
+                                        plan_year=args.year)
+    print(f"Ingest complete for plan year {args.year}.")
+    return 0
+
+def cmd_compare(args) -> int:
+    source = _build_source(args)
+    if source is None:
+        return 1
+    try:
+        premiums_year = source.premiums_plan_year()
+    except sources.RemoteDataError as e:
+        print(f"ERROR: {e}", file=sys.stderr)
+        return 1
+    if premiums_year is None:
+        # Guard before emitting any JSON so the skill sees a clean stream.
+        print("ERROR: premium data is missing or of unknown vintage — "
+              "run `pdpcompare ingest --year <year>` (local mode) or "
+              "check the plan-data server's /v1/health (remote mode)",
+              file=sys.stderr)
+        return 1
+    if premiums_year != args.year:
+        print(f"ERROR: premiums are for plan year {premiums_year}, you "
+              f"requested {args.year} — re-run ingest for {args.year} "
+              "(local mode) or wait for the server to load the new year "
+              "(remote mode)", file=sys.stderr)
+        return 1
+    for w in source.data_warnings():
+        print(f"WARNING: {w}", file=sys.stderr)
+    vintage = source.loaded_at()
+    rx = _rx_client()
+    in_path = Path(args.input)
+    records = (inputs.read_clients_xlsx(in_path) if in_path.suffix == ".xlsx"
+               else inputs.read_clients_json(in_path))
+    out_dir = Path(args.out)
+    clients_dir = Path(args.clients_dir) if args.clients_dir else None
+    summary = {"stay": 0, "switch": 0, "review": 0, "error": 0}
+    for rec_in in records:
+        try:
+            comp = engine.compare_client(source, rec_in, rx,
+                                         plan_year=args.year)
+            r = recommend.recommend(comp, switch_threshold=args.threshold,
+                                    near_tie_band=args.near_tie_band)
+            ws = worksheet.write_worksheet(comp, r, out_dir, vintage=vintage)
+            lt = letter.write_letter(comp, r, out_dir)
+            clientstore.save_client(rec_in, args.year, base_dir=clients_dir)
+            summary[r.action] += 1
+            print(json.dumps({"client_id": rec_in.client_id, "action": r.action,
+                              "savings": r.savings, "worksheet": str(ws),
+                              "letter": str(lt)}))
+        except engine.DrugNormalizationError as e:
+            summary["error"] += 1
+            print(json.dumps({"client_id": rec_in.client_id, "error": str(e),
+                              "candidates": e.candidates}))
+        except engine.StaleDataError as e:
+            # Stale data must stop the whole batch (spec §5). Mid-batch
+            # this can now happen in remote mode too: the server can
+            # blue-green swap plan years while a batch runs (409 →
+            # StaleDataError). Emit a clean machine-readable stop in both
+            # modes rather than a raw traceback.
+            summary["error"] += 1
+            print(json.dumps({"client_id": rec_in.client_id,
+                              "error": str(e),
+                              "batch": "stopped — plan-year mismatch; "
+                                       "re-run after re-ingest (local) or "
+                                       "when the server settles (remote)"}))
+            print(json.dumps({"summary": summary}))
+            return 2
+        except sources.RemoteDataError as e:
+            # Plan-data server outage: pause and report, same contract as
+            # the RxNav pause path (spec §7 — loud fail, no fallback).
+            summary["error"] += 1
+            print(json.dumps({"client_id": rec_in.client_id,
+                              "error": f"plan-data server error: {e}",
+                              "batch": "paused — re-run when the server "
+                                       "is back; completed clients "
+                                       "already have outputs"}))
+            print(json.dumps({"summary": summary}))
+            return 2
+        except httpx.HTTPError as e:
+            # RxNav outage: pause and report rather than degrading (spec §5).
+            summary["error"] += 1
+            print(json.dumps({"client_id": rec_in.client_id,
+                              "error": f"RxNav unreachable: {e!r}",
+                              "batch": "paused — re-run when RxNav is back; "
+                                       "completed clients are cached"}))
+            print(json.dumps({"summary": summary}))
+            return 2
+        except Exception as e:  # any other per-client failure: continue batch
+            summary["error"] += 1
+            print(json.dumps({"client_id": rec_in.client_id, "error": repr(e)}))
+    print(json.dumps({"summary": summary}))
+    return 0
+
+def cmd_status(args) -> int:
+    if args.api_url:
+        if not args.api_key:
+            print("ERROR: --api-key (or PDPCOMPARE_API_KEY) is required "
+                  "with --api-url", file=sys.stderr)
+            return 1
+        src = sources.RemoteSource(args.api_url, args.api_key)
+        try:
+            h = src.health()
+        except sources.RemoteDataError as e:
+            print(f"ERROR: {e}", file=sys.stderr)
+            return 1
+        for k in ("status", "plan_year", "premiums_plan_year",
+                  "loaded_at", "package_version", "last_update_check",
+                  "update_error"):
+            print(f"{k}: {h.get(k)}")
+        return 0 if h.get("status") == "ok" else 1
+    conn = _connect()
+    try:
+        year = plandata.db_plan_year(conn)
+    except Exception:
+        print("No plan data loaded. Run: pdpcompare ingest --year <year>")
+        return 1
+    print(f"Plan year: {year}")
+    try:
+        loaded_at, source_dir = conn.sql(
+            "SELECT loaded_at, source_dir FROM meta").fetchone()
+        print(f"Data vintage: loaded {loaded_at} from {source_dir}")
+    except Exception:
+        print("Data vintage: unknown (meta table missing loaded_at/source_dir)")
+    for t in ("plan_info", "formulary", "beneficiary_cost", "insulin_cost",
+              "pharmacy_network", "pricing", "premiums", "zip_state"):
+        try:
+            n = conn.sql(f"SELECT count(*) FROM {t}").fetchone()[0]
+        except Exception:
+            n = "MISSING"
+        print(f"  {t}: {n}")
+    return 0
+
+def cmd_update(args) -> int:
+    out = deskupdate.update_once(plan_year_override=args.plan_year,
+                                 force=args.force)
+    print(out.message)
+    if out.remap_request:
+        print(f"REMAP_REQUEST {out.remap_request}")
+    return 0 if out.updated or out.error_class is None else 1
+
+def cmd_instructions(args) -> int:
+    from importlib import resources
+    print(resources.files("pdpcompare.skilldoc")
+          .joinpath("INSTRUCTIONS.md").read_text(encoding="utf-8"))
+    return 0
+
+def cmd_doctor(args) -> int:
+    results = doctor.run_checks()
+    ready = True
+    for r in results:
+        line = f"{r.level.upper():<5} {r.name}: {r.detail}"
+        if r.remedy:
+            line += f" | remedy: {r.remedy}"
+        print(line)
+        ready = ready and r.level != "fail"
+    print("READY — run comparisons" if ready
+          else "NOT READY — fix the FAIL items above")
+    return 0 if ready else 1
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(prog="pdpcompare")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    pi = sub.add_parser("ingest")
+    pi.add_argument("--year", type=int, required=True)
+    pi.add_argument("--landscape",
+                     help="Optional: path to the CMS PDP Landscape CSV to "
+                          "override the premiums already loaded from the "
+                          "SPUF plan information file (deductibles stay "
+                          "SPUF-derived)")
+    pi.add_argument("--spuf-dir", help="Use an already-extracted SPUF dir")
+    pi.set_defaults(fn=cmd_ingest)
+
+    pc = sub.add_parser("compare")
+    pc.add_argument("--input", required=True)
+    pc.add_argument("--year", type=int, required=True)
+    pc.add_argument("--out", default=str(config.OUTPUT_DIR))
+    pc.add_argument("--threshold", type=float, default=100.0)
+    pc.add_argument("--near-tie-band", type=float,
+                    default=config.NEAR_TIE_BAND,
+                    help="Dollar band within which the top two plans are "
+                         "presented as effectively equivalent")
+    pc.add_argument("--clients-dir", default=None)
+    pc.add_argument("--api-url",
+                    default=os.environ.get("PDPCOMPARE_API_URL"),
+                    help="Remote plan-data server URL (remote mode)")
+    pc.add_argument("--api-key",
+                    default=os.environ.get("PDPCOMPARE_API_KEY"))
+    pc.set_defaults(fn=cmd_compare)
+
+    ps = sub.add_parser("status")
+    ps.add_argument("--api-url",
+                    default=os.environ.get("PDPCOMPARE_API_URL"))
+    ps.add_argument("--api-key",
+                    default=os.environ.get("PDPCOMPARE_API_KEY"))
+    ps.set_defaults(fn=cmd_status)
+
+    pu = sub.add_parser("update")
+    pu.add_argument("--plan-year", type=int, default=None,
+                    help="Override the plan year derived from the CMS "
+                         "release filename (plan-year cutover only)")
+    pu.add_argument("--force", action="store_true",
+                    help="Re-ingest even if the loaded release is current")
+    pu.set_defaults(fn=cmd_update)
+
+    pd = sub.add_parser("doctor")
+    pd.set_defaults(fn=cmd_doctor)
+
+    pin = sub.add_parser("instructions")
+    pin.set_defaults(fn=cmd_instructions)
+
+    args = p.parse_args(argv)
+    return args.fn(args)
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pdpcompare/clientstore.py

@@ -0,0 +1,47 @@
+"""Per-client per-plan-year JSON records. PHI: never leaves this machine."""
+from __future__ import annotations
+import json
+import os
+from pathlib import Path
+from . import config
+from .models import ClientRecord
+
+
+def validate_client_id(client_id: str) -> None:
+    """Client ids become filenames; reject anything that could escape the
+    store directory or collide on '.json'."""
+    cid = client_id.strip()
+    if not cid:
+        raise ValueError(f"invalid client_id {client_id!r}: empty")
+    forbidden = {"/", "\\", os.sep}
+    if os.altsep:
+        forbidden.add(os.altsep)
+    # separators are rejected outright, so the only possible ".." path
+    # segment left is the id being exactly ".."
+    if any(s in cid for s in forbidden) or cid == "..":
+        raise ValueError(f"invalid client_id {client_id!r}: must not contain "
+                         "path separators or '..' segments")
+
+
+# backwards-compatible alias for pre-rename callers
+_validate_client_id = validate_client_id
+
+
+def save_client(record: ClientRecord, plan_year: int,
+                base_dir: Path | None = None) -> Path:
+    validate_client_id(record.client_id)
+    base = base_dir or config.CLIENT_DIR
+    year_dir = base / str(plan_year)
+    year_dir.mkdir(parents=True, exist_ok=True)
+    path = year_dir / f"{record.client_id}.json"
+    path.write_text(json.dumps(record.to_dict(), indent=2))
+    return path
+
+
+def load_clients(plan_year: int, base_dir: Path | None = None) -> list[ClientRecord]:
+    base = base_dir or config.CLIENT_DIR
+    year_dir = base / str(plan_year)
+    if not year_dir.exists():
+        return []
+    return [ClientRecord.from_dict(json.loads(p.read_text()))
+            for p in sorted(year_dir.glob("*.json"))]

pdpcompare/config.py

@@ -0,0 +1,46 @@
+import os
+from pathlib import Path
+
+_SRC_ROOT = Path(__file__).resolve().parent.parent
+
+
+def resolve_root(src_root: Path, env: str | None, cwd: Path) -> Path:
+    """Anchor for data/ and output/. A source checkout (pyproject.toml
+    next to the package) anchors to the repo, exactly as before. A wheel
+    install must NOT anchor to site-packages — it uses the current
+    working directory (Cowork: the mounted working folder), overridable
+    via PDPCOMPARE_HOME."""
+    if env:
+        return Path(env)
+    return src_root if (src_root / "pyproject.toml").is_file() else cwd
+
+
+ROOT = resolve_root(_SRC_ROOT, os.environ.get("PDPCOMPARE_HOME"), Path.cwd())
+DATA_DIR = ROOT / "data"
+DB_PATH = DATA_DIR / "pdpcompare.duckdb"
+CACHE_DIR = DATA_DIR / "cache"
+OUTPUT_DIR = ROOT / "output"
+CLIENT_DIR = DATA_DIR / "clients"
+OVERRIDES_PATH = DATA_DIR / "header_overrides.json"
+
+PLAN_YEAR = 2026
+
+# Standard Part D benefit parameters. VERIFY EACH FALL when CMS publishes
+# the next year's defined standard benefit (deductible + IRA OOP cap).
+BENEFIT_YEARS: dict[int, dict] = {
+    2026: {"deductible_max": 615.0, "oop_cap": 2100.0},
+}
+
+# Presentation-only: when the top two complete plans are within this many
+# dollars/year, worksheets and letters say they are effectively equivalent.
+NEAR_TIE_BAND = 50.0
+
+# Desk staleness threshold — matches the server's PDP_STALE_DAYS default.
+STALE_DAYS = 100
+
+
+def intended_plan_year(now=None) -> int:
+    """AEP rule: Oct–Dec comparisons target NEXT calendar year."""
+    from datetime import datetime
+    now = now or datetime.now()
+    return now.year + 1 if now.month >= 10 else now.year

pdpcompare/costsim.py

@@ -0,0 +1,55 @@
+"""Month-by-month simulation of a plan year's out-of-pocket drug costs.
+
+Approximates the post-IRA (2025+) defined standard benefit:
+deductible -> initial coverage (tier cost-share) -> catastrophic ($0 after
+the annual OOP cap). Matches the accumulation model Medicare Plan Finder
+uses at the fidelity available in the CMS public files (plan-average
+retail pricing; manufacturer-discount amounts excluded).
+"""
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class PricedDrug:
+    monthly_full_cost: float   # unit_cost * quantity for one 30-day fill
+    cost_type: str             # "copay" | "coinsurance"
+    cost_amt: float            # dollars if copay; percent (e.g. 25.0) if coinsurance
+    ded_applies: bool
+    is_insulin: bool = False   # IRA statutory pricing (no deductible, $35 cap)
+
+
+INSULIN_MONTHLY_CAP = 35.0
+
+
+def simulate_annual_cost(priced_drugs: list[PricedDrug],
+                         deductible: float, oop_cap: float) -> float:
+    total_paid = 0.0
+    ded_remaining = deductible
+    for _month in range(12):
+        for d in priced_drugs:
+            if total_paid >= oop_cap:
+                continue
+            remaining_cost = d.monthly_full_cost
+            pay = 0.0
+            if d.is_insulin:
+                # IRA: the deductible never applies to covered insulin; the
+                # member pays the lesser of the plan share and $35/month.
+                if d.cost_type == "coinsurance":
+                    share = remaining_cost * d.cost_amt / 100.0
+                else:
+                    share = min(d.cost_amt, remaining_cost)
+                pay = min(share, INSULIN_MONTHLY_CAP, remaining_cost)
+            else:
+                if d.ded_applies and ded_remaining > 0:
+                    ded_part = min(remaining_cost, ded_remaining)
+                    pay += ded_part
+                    ded_remaining -= ded_part
+                    remaining_cost -= ded_part
+                if remaining_cost > 0:
+                    if d.cost_type == "coinsurance":
+                        pay += remaining_cost * d.cost_amt / 100.0
+                    else:
+                        pay += min(d.cost_amt, remaining_cost)
+            pay = min(pay, max(0.0, oop_cap - total_paid))
+            total_paid += pay
+    return round(total_paid, 2)

pdpcompare/db.py

@@ -0,0 +1,9 @@
+from pathlib import Path
+import duckdb
+from . import config
+
+
+def connect(db_path: Path | None = None) -> duckdb.DuckDBPyConnection:
+    path = db_path or config.DB_PATH
+    path.parent.mkdir(parents=True, exist_ok=True)
+    return duckdb.connect(str(path))