What is the Tuva Project and why should data engineers care

Healthcare claims data is some of the most complex structured data in existence. A single inpatient stay can span dozens of claim lines, each with procedure codes, diagnosis codes, revenue codes, place of service codes, and modifiers — none of which mean anything without the reference tables and business logic to interpret them.

The Tuva Project is an open-source dbt package that takes raw claims and builds the analytics layer on top of them. It’s what you’d build yourself over 18 months if you worked at a health plan or ACO long enough.

What Tuva actually is

Tuva is a dbt package. You install it via packages.yml, point it at your raw claims tables by setting its source variables, and run dbt run. It produces a set of mart tables organized around clinical and financial analytics use cases.

The core package is tuva-inc/the_tuva_project. As of version 0.17.2, it contains roughly 879 models organized into data marts:

Core — normalized claim lines, patients, providers, encounters
Quality Measures (HEDIS) — measure calculations for AMB, ADH, BCS, CBP, and others
HCC Suspecting — identifies suspected Hierarchical Condition Categories based on prior-year diagnosis codes
HCC Recapture — tracks whether suspected HCCs appear in current-year claims
CCSR — Clinical Classifications Software Revised groupings for diagnoses and procedures
Chronic Conditions — chronic condition flags at the patient level
ED Classification — emergency department visit classification (avoidable vs. non-avoidable)
Readmissions — 30-day readmission flags
Financial PMPM — per-member-per-month spend summaries
Data Quality (DQI) — fill rates and anomaly flags for every input field

The input data model

Tuva expects specific source table shapes. For Medicare fee-for-service claims the standard inputs are:

Medical claims: claim_id, claim_line_number, patient_id, claim_type, service dates, procedure codes, diagnosis codes, paid amounts
Eligibility: patient_id, enrollment_start, enrollment_end, payer, plan
Pharmacy claims (optional, for Part D)

You map your raw tables to these shapes using Tuva’s staging layer. The 167k synthetic Medicare claims in this project map cleanly to Tuva’s expected schema after minimal transformation.

Why this matters for data engineers

Before Tuva, a healthcare analytics team building on claims data would spend months writing and testing:

Encounter grouping logic (inpatient vs. outpatient vs. professional)
HEDIS denominator and numerator logic
HCC mapping from ICD-10 codes to CMS HCC model categories
Chronic condition flagging from CCSR groupings

Each of these is a non-trivial problem. HEDIS specification documents run to hundreds of pages. HCC mapping requires the current year’s CMS coefficients and mapping tables. Getting these wrong produces incorrect quality scores that have regulatory consequences in a Medicare Advantage or MSSP/ACO contract.

Tuva packages this logic into tested, versioned dbt code. When CMS updates the HCC model coefficients or HEDIS specifications change, the package updates. You don’t have to re-derive the logic from the specification.

How to install it

In packages.yml:

packages:
  - package: tuva-inc/the_tuva_project
    version: 0.17.2

In dbt_project.yml, set the source variables Tuva needs:

vars:
  tuva_project_release: "0.17.2"
  claims_enabled: true
  clinical_enabled: false
  source_database: "your_db"
  source_schema: "your_raw_schema"

Run dbt deps to install, then dbt seed to load the reference tables (ICD-10 codes, HCC mappings, CCSR groupings), then dbt run.

The tradeoffs

Tuva is a large package. On a modest laptop, a full dbt run takes several minutes even on DuckDB. The mart tables it produces are designed for further aggregation — they’re not ready to hand directly to a BI tool without a second modeling layer on top.

The DQI mart is the most immediately useful output for a new dataset. It produces fill rates and anomaly flags for every input field, which gives a fast answer to “how good is this data before I build anything on top of it?”

Running Tuva on DuckDB locally is viable for development and exploration. The intended production path is a cloud warehouse — Snowflake, BigQuery, or Redshift — where the models run in parallel and the reference seed tables don’t need to be re-downloaded on every run.