Suspecting SDK

For every drug, drug_hcc_suspect lists the CMS-HCC and RxHCC categories it points at, the share of the drug's use behind each, and a confidence tier. The SDK joins that to a member's fills and to the diagnoses already on their medical claims.

The SDK is delivered during onboarding as an installable Python package, twinfyrx_sdk: one module, a schema mapping template, a demo and a synthetic claims set. It generates SQL, has no dependencies of its own, and fetches nothing at install or run time.

pip install ./sdk                 # from the delivered folder
pip install "./sdk[demo]"         # adds duckdb and pandas for the demo

from twinfyrx_sdk import coverage_sql, suspects_sql, evidence_sql, SuspectSchema

# or print the SQL and skip Python altogether
python -m twinfyrx_sdk --year 2026 > suspects.sql

The SDK ships with 300 synthetic members on real drugs and real NDCs, already joined to the TwinFyRx tables they need, so the first run takes no setup.

pip install "./sdk[demo]"
python -m twinfyrx_sdk.demo
python -m twinfyrx_sdk.demo --model rxhcc_v08 --min-tier unrated --top 20

The demo prints the input check, open suspects by status and tier, and the top of the worklist with the drugs behind each suspect. The synthetic members show the mechanics — statuses, tiers, ordering — not accuracy. The drugs, NDCs, categories and tiers they join to are the published tables.

The scan reads two of your tables and five of ours. Map yours with views, or pass your table and column names through SuspectSchema.

from twinfyrx_sdk import SuspectSchema

schema = SuspectSchema(
    rx_claims_table="pharmacy.fills",
    rx_member_id="pat_id",
    rx_ndc="ndc11",
    rx_fill_date="date_of_service",

    medical_claims_table="medical.claim_dx",
    mc_member_id="pat_id",
    mc_icd10_code="dx_code",        # dotted or dotless, either works
    mc_service_date="service_date",
)

Run coverage_sql() before the scan. A wrong NDC or member-id format does not raise an error — it returns a short, plausible-looking list. Eight counts show whether your claims join.

print(coverage_sql(year=2026, schema=schema))

step  check_name                                                  row_count
   1  pharmacy fills in 2026                                           3785
   2  - with an NDC found in ndc_crosswalk                             3785
   3  - for a drug with a high or moderate cms_hcc_v28 category        1416
   4  members with a fill in 2026                                       300
   5  - who also appear in medical_claims                               300
   6  diagnosis rows in 2025-2026                                      1100
   7  - with a code found in icd10                                     1100
   8  - in a cms_hcc_v28 category                                       492

Step 2 near zero is an NDC format problem, not a coverage problem. Step 5 low means member ids differ between your pharmacy and medical tables, and every suspect will come back as a gap. Steps 3 and 8 are normally a minority: most drugs are used for several conditions, and most diagnoses carry no risk-adjustment category.

suspects_sql() returns the statement for a measurement year. Run it wherever your claims live, or use find_suspects() to execute it on a DuckDB connection and get a DataFrame.

from twinfyrx_sdk import suspects_sql, find_suspects

# The SQL, to run in your warehouse
sql = suspects_sql(
    year=2026,                    # calendar year of the service dates
    model_key="cms_hcc_v28",      # or cms_hcc_v24, rxhcc_v08
    min_tier="moderate",          # high and moderate suspects only
    schema=schema,
)

# Or execute directly on DuckDB
worklist = find_suspects(conn, year=2026, schema=schema)   # open suspects only

Fills count in the measurement year; diagnoses are read for that year and the one before. For Medicare Advantage, the measurement year is the year before the payment year. The statement has six parts: the member's drugs in the year, what each drug points at, a per-category roll-up across the member's drugs, the categories already coded this year and last, CMS's hierarchies, and the status for each.

One row per member and condition category.

evidence_sql() returns the reason for each row — the drugs behind it, one row per member, category and drug. Join it to the worklist on member_id and cc.

The tier is the claim to act on; the share is the estimate behind it. Tiers are cut where the shares hold up against AHRQ MEPS prescription–diagnosis data.