🏁 Getting Started

To run Tuva you need to do the following:

Load your healthcare data (e.g. claims, EHR) into a data warehouse (e.g. Snowflake, Databricks)
Install dbt -- a free open-source tool for transforming data inside your data warehouse
Create a new dbt project and connect that project to your data warehouse
Map your raw healthcare data to the Tuva Input Layer
Import the Tuva package into your dbt project
Run the entire dbt project (i.e. execute dbt build)

Below we describe how to do this in more detail. If you do not have access to healthcare data yet, or if you just want to run Tuva locally first, start with the demo project on DuckDB using the exact steps below.

Run the Demo Locally with DuckDB

The commands below were validated locally against the current tuva-health/demo repository on March 14, 2026. In that validation run, dbt deps resolved tuva-health/the_tuva_project to 0.17.1.

Clone the repo and move into it.

git clone https://github.com/tuva-health/demo.git
cd demo

Create and activate a Python virtual environment.

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip

Install dbt with the DuckDB adapter.

python -m pip install dbt-duckdb

This installs both dbt-core and the DuckDB adapter for dbt. You do not need a separate pip install dbt-core.

Create a local dbt profile for the demo project. The demo project's dbt_project.yml uses the profile name default, so define that profile in a user-managed profile directory instead of using the CI profiles under integration_tests/profiles.

mkdir -p .dbt
cat > .dbt/profiles.yml <<'EOF'
default:
  target: dev
  outputs:
    dev:
      type: duckdb
      path: "{{ env_var('DEMO_DUCKDB_PATH') }}"
      threads: 4
EOF

Point that local dbt profile at a DuckDB file.

export DBT_PROFILES_DIR="$PWD/.dbt"
export DEMO_DUCKDB_PATH="$PWD/demo.duckdb"

Verify that dbt can connect to DuckDB.

dbt debug

Install the dbt packages.

dbt deps

Build the demo project with claims, clinical, and provider attribution all enabled.

dbt build

This creates a local DuckDB database file at demo.duckdb. The build also downloads the synthetic input data, terminology, and value sets from tuva-public-resources, so you need an internet connection while it runs.

This full dbt build path was validated locally on March 14, 2026 against tuva-health/the_tuva_project 0.17.1 on DuckDB. The run completed successfully in about 41 minutes on a fresh local database file. You should still expect warning-level data quality output from the demo's synthetic source data, but the build finishes successfully with claims, clinical, and provider attribution all turned on.

After the build finishes, you can inspect the output locally. If you want to use the DuckDB command-line tool for that, install it first:

brew install duckdb

Then open the database:

duckdb demo.duckdb

select count(*) from core.patient;
select count(*) from core.encounter;

The video below is still a helpful walkthrough, but the commands above are the current runbook.

Run the Demo Locally with DuckDB​

Run the Demo Locally with DuckDB