tuva-core

What Tuva Core models

Tuva Core is the dbt package that aggregates and transforms payer claims, EHR, and other healthcare data into a common analytics and AI ready data model inside a cloud data warehouse. The package includes input layer contracts for payer and provider source data, normalized layer models, claims preprocessing models, core data model tables, neutral data quality result tables, and Tuva Data Assets such as terminology, value sets, provider data, and synthetic data. The README frames this as a way to stop rebuilding the same healthcare data transformations in every warehouse. Instead of writing claims and terminology logic from scratch, a team installs the package and points it at their source tables through the input layer contracts. The core data model is the shared target that downstream analytics and AI work against, so different source systems land in one shape. The neutral data quality result tables give a consistent place to record test outcomes. The Tuva Data Assets ship terminology and value sets that healthcare analytics usually has to source separately, plus provider data and synthetic data for testing. Because it is a dbt package, the transformations are SQL models with YAML metadata, and they run wherever dbt runs. The documentation, DAG viewer, and getting started guides live on thetuvaproject.com, while the code and the data asset inventory live in this repository. The design goal is a reusable foundation rather than a one off pipeline.

Local development setup

The README describes a recommended local setup using Python 3.10 or later, DuckDB, and dbt-core with dbt-duckdb. The integration_tests project acts as the local development project: it maps Tuva synthetic data into the input layer, imports the local package, and exercises the Tuva Core path. A local DuckDB profile goes in the user's dbt profiles.yml, and the README recommends one thread for seed stability. The helper script scripts/dbt-local drives the local runs, with deps and build --full-refresh as the first steps. The dbt seed and dbt build commands load Tuva Data Assets from an immutable public object storage snapshot that matches the installed Tuva Core version; for example, version 1.0.0 loads from tuva-core/1.0.0/. A plain dbt run assumes those relations already exist, so on a fresh database you run seed or build first. Once assets are loaded, you iterate with dbt run. The docs site and DAG viewer live in sibling repositories and, during local development, read dbt, YAML, and SQL metadata from this checkout through the TUVA_CORE_PATH environment variable. The example shows setting TUVA_CORE_PATH to the parent tuva-core directory and running the docs and dag-viewer builds. This separation keeps the package itself free of presentation code while letting contributors see the model graph locally before publishing changes.

Variables and data assets

Tuva Core is configured through dbt variables set under the vars key in dbt_project.yml. The README groups common variables into a few categories. Domain enablement covers claims_enabled, clinical_enabled, and provider_attribution_enabled. Data quality is toggled with data_quality_enabled. Data assets use custom_bucket_name and tuva_seed_buckets. Synthetic data validation uses use_synthetic_data and synthetic_data_size. Runtime metadata and schemas use tuva_last_run and tuva_schema_prefix. Extension columns use passthrough. The package derives its data asset version from the installed package version, so projects do not maintain separate pins for terminology, value sets, provider data, or synthetic data. Every Tuva Core release that ships external data assets has one complete immutable snapshot at tuva-core slash the package version, containing terminology, provider-data, synthetic-data with small and large sizes, and value-sets. The physical object names match their dbt seed resource names and end in csv.gz. A data_assets.yml file is the package owned inventory used by the release publisher, and each storage location receives a release receipt only after all of its payload objects verify. That receipt binds the snapshot to the exact 40 character hash of the contents. The effect is that a given Tuva Core version always loads the same terminology and synthetic data, which makes local and production runs reproducible.

Editorial conclusion

The package is a Python dbt project and its source lives at the tuva-health tuva-core repository, documented at thetuvaproject.com.