omop-duck-db 0.2.0__tar.gz

omop_duck_db-0.2.0/.Rbuildignore

@@ -0,0 +1,31 @@
+^renv$
+^renv\.lock$
+^\.git$
+^\.github$
+^\.gitignore$
+^\.Rproj\.user$
+^\.claude$
+^tasks$
+^computed_tasks$
+^data$
+^out$
+^python$
+^vocabulary_download_v5_.*$
+(^|/)[^/]*\.duckdb$
+^config$
+^dist$
+^build$
+^.*\.egg-info$
+^pyproject\.toml$
+^requirements.*\.txt$
+^\.venv$
+^\.pytest_cache$
+^__pycache__$
+^\.Rprofile$
+^README\.Rmd$
+^LICENSE\.md$
+^_pkgdown\.yml$
+^docs$
+.dockerignore
+^Dockerfile$
+^scripts$

omop_duck_db-0.2.0/.Rprofile

@@ -0,0 +1 @@
+source("renv/activate.R")

omop_duck_db-0.2.0/.dockerignore

@@ -0,0 +1,36 @@
+.git
+.gitignore
+.Rbuildignore
+.Rproj.user
+.vscode
+NEWS.md
+*.log
+*.swp
+*.swo
+*~
+.DS_Store
+revdep/
+pkgdown/
+renv/library
+renv/staging
+
+# Project-specific: large generated artifacts and real credentials --
+# never send these to the Docker build context.
+*.duckdb
+*.duckdb.wal
+vocabulary_download_v5_*/
+vocabulary_download_v5_*.zip
+config/*.yml
+!config/*.yml.example
+data/
+out/
+dist/
+build/
+*.egg-info/
+docs/
+.venv/
+__pycache__/
+.pytest_cache/
+tasks/
+computed_tasks/
+.claude/

omop_duck_db-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,105 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  r-check:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    env:
+      GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
+      # Avoid the renv-autoload trap we hit locally/in Docker: this job
+      # installs deps directly via r-lib/actions, not through renv::restore().
+      RENV_CONFIG_AUTOLOADER_ENABLED: false
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: r-lib/actions/setup-r@v2
+        with:
+          use-public-rspm: true
+
+      - uses: r-lib/actions/setup-r-dependencies@v2
+        with:
+          extra-packages: any::rcmdcheck
+          needs: check
+
+      - uses: r-lib/actions/check-r-package@v2
+        with:
+          error-on: '"warning"'
+          upload-snapshots: true
+
+  python-test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.10", "3.11", "3.12"]
+    env:
+      RENV_CONFIG_AUTOLOADER_ENABLED: false
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      # R is needed too: tests/test_etl_parity.py shells out to Rscript to
+      # run the R ETL and diff it against the Python one.
+      - uses: r-lib/actions/setup-r@v2
+        with:
+          use-public-rspm: true
+
+      - name: Install R package + its hard dependencies
+        run: Rscript -e "install.packages(c('DBI','duckdb','stringr','yaml')); install.packages('.', repos = NULL, type = 'source')"
+
+      - name: Install Python package (+ dev extras)
+        run: pip install -e ".[dev]"
+
+      - name: Run pytest
+        run: pytest tests/ -v
+
+  python-only:
+    # Proves the Python package works standalone with no R installed at all --
+    # the real target for this: GPU/deep-learning machines running just the
+    # ETL/inference side, no R toolchain. tests/test_etl_parity.py must SKIP
+    # here (via its shutil.which("Rscript") is None guard), not fail; if it
+    # fails instead, that guard has regressed.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install Python package (+ dev extras) -- no R anywhere in this job
+        run: pip install -e ".[dev]"
+
+      - name: Run pytest (parity test should skip, not fail)
+        run: pytest tests/ -v
+
+  docker-build:
+    # Docker isn't available the same way on windows-latest/macos-latest
+    # runners; this validates the containerized path on Linux only.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: docker/setup-buildx-action@v3
+
+      - name: Build image (runs both test suites at build time)
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: false
+          tags: omopduckdb:ci
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

omop_duck_db-0.2.0/.github/workflows/pkgdown.yml

@@ -0,0 +1,58 @@
+name: pkgdown
+
+# Deploys the pkgdown reference site to GitHub Pages on every push to main.
+#
+# One-time manual setup required before this will work:
+#   Repo Settings -> Pages -> Build and deployment -> Source: "GitHub Actions"
+# Without that, the deploy job below will fail even if the site builds fine.
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pkgdown-pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    env:
+      RENV_CONFIG_AUTOLOADER_ENABLED: false
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: r-lib/actions/setup-r@v2
+        with:
+          use-public-rspm: true
+
+      - uses: r-lib/actions/setup-pandoc@v2
+
+      - uses: r-lib/actions/setup-r-dependencies@v2
+        with:
+          extra-packages: any::pkgdown, local::.
+          needs: website
+
+      - name: Build site
+        run: pkgdown::build_site_github_pages(new_process = FALSE, install = FALSE)
+        shell: Rscript {0}
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

omop_duck_db-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,65 @@
+name: Release (Python -> PyPI)
+
+# Builds and checks the Python distribution on every version tag push, then
+# publishes to PyPI -- but only after a human approves it. Nothing here can
+# publish without that manual click; and even then, it needs one-time setup
+# on both PyPI and GitHub before it can succeed at all (see below).
+#
+# One-time setup required before publish-pypi can work:
+#   1. Create the PyPI project (or use "pending publisher" for one that
+#      doesn't exist yet: https://pypi.org/manage/account/publishing/).
+#   2. Register this repo + workflow file as a Trusted Publisher on PyPI --
+#      no token/secret needed, PyPI verifies GitHub's OIDC token instead.
+#   3. Repo Settings -> Environments -> New environment named
+#      "pypi-release" -> add yourself as a required reviewer. That's the
+#      approval gate: the publish job pauses here until manually approved,
+#      every single time, regardless of how the tag push happened.
+#
+# Until all three exist, build-check still runs and is useful on its own
+# (confirms the tag actually produces a valid, installable distribution);
+# publish-pypi will simply fail or sit waiting for an environment that
+# doesn't exist yet, and can be safely ignored until you're ready.
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+jobs:
+  build-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - run: pip install build twine
+
+      - run: python -m build
+
+      - run: twine check dist/*
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: python-dist
+          path: dist/
+
+  publish-pypi:
+    needs: build-check
+    runs-on: ubuntu-latest
+    # This environment is the manual-approval gate -- see setup notes above.
+    environment:
+      name: pypi-release
+      url: https://pypi.org/p/omop-duck-db
+    permissions:
+      id-token: write # Trusted Publishing (OIDC) -- no PYPI_API_TOKEN secret needed
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: python-dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

omop_duck_db-0.2.0/.github/workflows/test-coverage.yml

@@ -0,0 +1,88 @@
+name: Test Coverage
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  r-coverage:
+    runs-on: ubuntu-latest
+    env:
+      GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
+      RENV_CONFIG_AUTOLOADER_ENABLED: false
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: r-lib/actions/setup-r@v2
+        with:
+          use-public-rspm: true
+
+      - uses: r-lib/actions/setup-r-dependencies@v2
+        with:
+          extra-packages: any::covr, any::xml2, local::.
+          needs: coverage
+
+      - name: Calculate R Test Coverage
+        run: |
+          cov <- covr::package_coverage()
+          covr::to_cobertura(cov, filename = "r_coverage.xml")
+        shell: Rscript {0}
+
+      - name: Upload R Coverage Report
+        uses: actions/upload-artifact@v4
+        with:
+          name: r-coverage-report
+          path: r_coverage.xml
+          if-no-files-found: ignore
+
+      - name: Upload R Coverage to Codecov
+        uses: codecov/codecov-action@v4
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: ./r_coverage.xml
+          flags: r
+          fail_ci_if_error: false
+
+  python-coverage:
+    runs-on: ubuntu-latest
+    env:
+      RENV_CONFIG_AUTOLOADER_ENABLED: false
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - uses: r-lib/actions/setup-r@v2
+        with:
+          use-public-rspm: true
+
+      - name: Install R package (required by parity tests)
+        run: Rscript -e "install.packages(c('DBI','duckdb','stringr','yaml')); install.packages('.', repos = NULL, type = 'source')"
+
+      - name: Install Python package with dev dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Run pytest with coverage
+        run: pytest tests/ --cov=python/omop_etl --cov-report=xml:py_coverage.xml --cov-report=term
+
+      - name: Upload Python Coverage Report
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-coverage-report
+          path: py_coverage.xml
+          if-no-files-found: ignore
+
+      - name: Upload Python Coverage to Codecov
+        uses: codecov/codecov-action@v4
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: ./py_coverage.xml
+          flags: python
+          fail_ci_if_error: false

omop_duck_db-0.2.0/.gitignore

@@ -0,0 +1,48 @@
+# Large generated/downloaded artifacts (synced via Google Drive instead, see R/gdrive_sync.R)
+*.duckdb
+*.duckdb.wal
+vocabulary_download_v5_*/
+vocabulary_download_v5_*.zip
+out/
+
+# Claude Code / ComputeGate session scratch (not part of the project)
+tasks/
+computed_tasks/
+
+# R
+.Rhistory
+.Rdata
+.Rproj.user/
+renv/library/
+renv/local/
+renv/staging/
+README.knit.md
+*_files/
+docs/
+Meta/
+doc/
+/*.tar.gz
+/*.Rcheck/
+
+# Python packaging build artifacts
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+
+# Python
+__pycache__/
+*.pyc
+.venv/
+venv/
+
+# Credentials / tokens - never commit
+.env
+*token*.json
+*credentials*.json
+config/*.yml
+!config/*.yml.example
+
+# Raw site data, manifests, and row samples (may contain PHI-adjacent
+# patient-level data) - never commit anything under here
+secrets/

omop_duck_db-0.2.0/DESCRIPTION

@@ -0,0 +1,34 @@
+Package: omopduckdb
+Title: Build and Populate an OMOP CDM v5.4 Database in DuckDB
+Version: 0.2.0
+Authors@R: person("J Kyle", "Armstrong", email = "j.kyle.armstrong@gmail.com", role = c("aut", "cre"), comment = c(ORCID = "0000-0002-4269-0121"))
+Description: Tools for building an OMOP Common Data Model (CDM) v5.4 schema
+    in DuckDB, loading the OHDSI Athena vocabulary (from a local download or
+    live from BigQuery), and mapping PCORnet-format source data into the CDM
+    via parallel R and Python ETL implementations that share the same
+    concept-mapping SQL. Also includes a Google Drive sync helper for the
+    large generated database/vocabulary files.
+License: GPL-3 | MIT + file LICENSE
+URL: https://github.com/jkylearmstrong/omop-duck-db, https://jkylearmstrong.github.io/omop-duck-db
+BugReports: https://github.com/jkylearmstrong/omop-duck-db/issues
+Encoding: UTF-8
+Roxygen: list(markdown = TRUE)
+Depends:
+    R (>= 4.1)
+Imports:
+    DBI,
+    duckdb,
+    stringr,
+    yaml
+Suggests:
+    googledrive,
+    bigrquery,
+    CommonDataModel,
+    covr,
+    xml2,
+    testthat (>= 3.0.0),
+    usethis (>= 3.2.1)
+Config/testthat/edition: 3
+Config/roxygen2/version: 8.0.0
+Remotes:  
+    jkylearmstrong/usethis

omop_duck_db-0.2.0/Dockerfile

@@ -0,0 +1,76 @@
+# syntax=docker/dockerfile:1.6
+
+# Multi-stage build for R package: omopduckdb
+# (also installs and tests the Python package, omop-duck-db, since this repo
+# ships both -- usethis::use_dockerfile() only knows about the R side)
+#
+# NOTE on the repos date: usethis::use_dockerfile() date-pins the Posit
+# Package Manager snapshot to Sys.Date() at generation time. On this machine
+# that produced a *future* date (2026-07-31) that Posit's snapshot service
+# won't have data for yet in the real world -- swapped for the rolling
+# `/latest` alias instead. Worth fixing upstream in the PR: pinning to
+# Sys.Date() is only safe if that's guaranteed to be <= the real current date.
+
+# Stage 1: builder
+FROM rocker/r-ver:4.4.2 AS builder
+
+# The repo's .Rprofile activates renv on load; renv's own project library is
+# irrelevant here (this image installs straight into /rlib instead), and
+# without this it silently swaps .libPaths() to an empty renv library,
+# hiding everything just installed. Same fix needed locally on Windows.
+ENV RENV_CONFIG_AUTOLOADER_ENABLED=FALSE
+ENV R_LIBS=/rlib
+WORKDIR /build
+
+# Install system dependencies (git from the generator; python3 added so this
+# stage can also build the Python package)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        git python3 python3-pip python3-venv libicu-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install R packages into a dedicated library
+RUN mkdir -p /rlib && Rscript -e 'install.packages(c("bigrquery", "CommonDataModel", "DBI", "duckdb", "googledrive", "quarto", "stringr", "testthat", "usethis", "yaml"), repos = "https://packagemanager.posit.co/cran/__linux__/noble/latest", lib = "/rlib")'
+
+# Build + test both packages in the builder stage, so a failing test fails
+# the image build, not just a later `docker run`.
+COPY . /build
+RUN R_LIBS=/rlib R CMD INSTALL --no-multiarch --with-keep.source --install-tests /build --library=/rlib
+RUN cd /build/tests && R_LIBS=/rlib Rscript testthat.R
+
+RUN python3 -m venv /pyvenv \
+    && /pyvenv/bin/pip install --no-cache-dir "/build[dev]" \
+    && R_LIBS=/rlib PATH="/pyvenv/bin:$PATH" /pyvenv/bin/python -m pytest /build/tests -v
+
+# Stage 2: final runtime
+FROM rocker/r-ver:4.4.2
+
+LABEL org.opencontainers.image.title="omopduckdb"
+
+# Create non-root user (skip if already exists)
+RUN id -u ruser >/dev/null 2>&1 || useradd -m -u 1000 ruser
+
+# Install runtime system deps
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        git python3 python3-venv libicu-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /workspace
+
+# Copy R packages and the built Python venv from builder
+COPY --from=builder /rlib /rlib
+COPY --from=builder /pyvenv /pyvenv
+ENV RENV_CONFIG_AUTOLOADER_ENABLED=FALSE
+ENV R_LIBS=/rlib
+ENV PATH="/pyvenv/bin:$PATH"
+
+# Copy project source
+COPY --chown=ruser:ruser . .
+
+# Ensure working directory is owned by non-root user
+RUN chown -R ruser:ruser /workspace
+
+# Switch to non-root user
+USER ruser
+
+# Default: R interactive
+CMD ["R", "--no-save"]

omop_duck_db-0.2.0/LICENSE

@@ -0,0 +1,2 @@
+YEAR: 2026
+COPYRIGHT HOLDER: J Kyle Armstrong

omop_duck_db-0.2.0/LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2026 J Kyle Armstrong
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

omop_duck_db-0.2.0/NAMESPACE

@@ -0,0 +1,17 @@
+# Generated by roxygen2: do not edit by hand
+
+export(build_condition_era)
+export(build_drug_era)
+export(build_observation_period)
+export(build_schema)
+export(check_vocabulary_version)
+export(etl_pcornet)
+export(export_unmapped_codes)
+export(gdrive_download_latest)
+export(gdrive_upload_snapshot)
+export(import_source_to_concept_map)
+export(import_usagi_mappings)
+export(load_from_bigquery)
+export(load_vocabulary)
+export(remap_all)
+export(remap_cdm_table)

omop_duck_db-0.2.0/NEWS.md

@@ -0,0 +1,41 @@
+# omopduckdb 0.2.0
+
+### Architecture & Production Hardening
+- **Vectorized Set-Based Mapping**: Replaced correlated scalar subqueries in concept resolution macros with vectorized hash joins across `concept`, `concept_relationship` (`Maps to`), and `source_to_concept_map`, dramatically improving query execution speed on large extracts.
+- **Deterministic Surrogate Primary Keys**: Eliminated hash collision risks and non-deterministic IDs by migrating all CDM occurrence tables to deterministic `ROW_NUMBER() OVER (...) + MAX(id)` sequence generation.
+- **Date & Datetime Macro Parsing**: Added flexible multi-format date and datetime parsing macros (`parse_omop_date` and `parse_omop_datetime`) supporting `%Y-%m-%d`, `%Y%m%d`, `%d%b%Y`, and `%m/%d/%Y`.
+- **Source Column Resilience**: Implemented automated source view preparation (`prepare_source_view`) handling case-insensitive column names, de-identified ID aliases (`ssid` to `PATID`), and projecting `NULL` for missing optional columns without failing execution.
+- **Mandatory OHDSI Synthesizers**: Added automated generation for required OMOP CDM v5.4 tables: `observation_period` (computed from patient event boundaries), `drug_era` (30-day persistence window collapse), `condition_era` (30-day persistence window collapse), and `cdm_source` (`cdm_version_concept_id = 756265`).
+- **Modular Death Table Handling**: Ingestion of `death.csv` is now optional and skips gracefully with an informative message if omitted, while deduplicating patient death records when provided.
+
+### Vocabulary Management & Remapping Helpers
+- **CPT4 Null Concept Name Sanitization**: Athena CPT4 concepts with null names are automatically replaced with `'CPT4 ' || concept_code` upon ingestion to prevent downstream failures.
+- **Vocabulary Version Inspector**: Added `check_vocabulary_version()` in both R and Python to query vocabulary metadata and verify Athena release dates.
+- **Usagi & Custom Mapping Tools**: Added `import_source_to_concept_map()` and `import_usagi_mappings()` to easily load custom crosswalks directly into `source_to_concept_map`, and `export_unmapped_codes()` to audit unmapped source codes into CSV format ready for OHDSI Usagi review.
+- **In-Place Retroactive Remapping**: Added `remap_cdm_table()` and `remap_all()` supporting dry-run previews and transactional in-place re-mapping of existing CDM tables when vocabularies are updated, with automatic era synthesizer regeneration.
+
+### Dual-Language Parity
+- Verified 100% byte-for-byte parity across R and Python ETL implementations for all 12 CDM tables in `tests/test_etl_parity.py`.
+
+# omopduckdb 0.1.1
+
+- Added unified cross-language test coverage tracking (`covr` for R, `pytest-cov` for Python) and a dedicated `.github/workflows/test-coverage.yml` CI workflow.
+- Created consolidated developer release scripts (`scripts/release.py` and `scripts/release.R`) for automated dual-package version bumping, Quarto rendering, test suite execution, wheel building, and git tagging.
+- Enhanced Docker container configuration for multi-stage testing and deployment.
+
+# omopduckdb 0.1.0
+
+Initial packaged release.
+
+- Build an OMOP CDM v5.4 schema in DuckDB from a shared, checked-in DDL.
+- Load and refresh the OHDSI Athena vocabulary, transactionally per table.
+- Map PCORnet-format source data into the CDM via parallel R and Python ETL
+  implementations that share the same concept-mapping SQL, verified to
+  produce identical output against a shared test fixture.
+- Load OMOP-shaped tables directly from BigQuery (vocab refresh or demo data),
+  as an alternative to a local vocabulary download.
+- Sync the generated database and vocabulary archive through Google Drive
+  instead of committing large binaries to git.
+- Packaged as both an installable R package (`DESCRIPTION`/`NAMESPACE`,
+  `testthat` suite, `pkgdown` site) and a Python package (`pyproject.toml`,
+  `pytest` suite).

omop_duck_db-0.2.0/NOTES.md

@@ -0,0 +1,25 @@
+# Notes
+
+Internal working notes on where this package came from and where it's headed. See `README.Rmd`/`README.md` for the technical package overview.
+
+## Where it came from
+
+`omop-duck-db` (R package `omopduckdb`) builds and populates an OMOP CDM v5.4 database in DuckDB, loads the OHDSI Athena vocabulary, and maps PCORnet-format source data into the CDM — with parallel R and Python ETL implementations sharing the same schema and concept-mapping SQL, so either language gets the same result. It's deliberately the public/generic piece of a bigger initiative: no institution names, no site specifics, no protected data, ever — real-world use against production data happens entirely outside this repo, against your own infrastructure (see `kyle_out_zip/omop_bridge/` for that private, site-aware layer).
+
+## Key decisions (and why)
+
+- **License: dual `GPL-3 | MIT`**, changed from plain MIT on 2026-08-05 to match the rest of the public track (`TempleCBE`, `pslongSim`, `ML-PScore`, `quarto_temple_brand`). Still local-only, not pushed.
+- **Schema is generated, never hand-declared.** `inst/extdata/5.4/duckdb/*.sql` (from OHDSI's `CommonDataModel` R package) is the single source of truth for both ETL paths — this is why `kyle_out_zip`'s bridging script calls this package's real entrypoint instead of writing new mapping SQL; a hand-rolled alternative (`kyle_out_zip/omop_duckdb_gpu_server_integration_plan.md`) diverged from this and would have produced a broken database (wrong ID scheme, wrong glob paths, invented columns).
+
+## Current status (2026-08-05)
+
+Verified directly against source this session, not assumed:
+- The Python ETL (`build_omop_cdm.py`) has **no `VITAL` → `MEASUREMENT` mapping** yet — only `demographic`, `provider`, `encounter`, `diagnosis`, `procedures`, `lab_result_cm`, `prescribing` are handled.
+- `load_vocabulary()` is **R-only** — no Python equivalent exists yet.
+- PCORnet source file/column expectations were cross-checked against `tests/fixtures/pcornet_sample/` and confirmed to match what `kyle_out_zip`'s real per-site extracts actually look like (modulo one `ssid`→`PATID` header rename).
+
+## Where it's heading
+
+- Close the two gaps above (`VITAL` mapping, Python-side vocabulary loader) — needed before `kyle_out_zip`'s eDerri pipeline can capture vitals data or run entirely in Python without an R fallback.
+- Commit + push the license change.
+- Once `kyle_out_zip/omop_bridge/` runs successfully against real site data, OHDSI's DataQualityDashboard is the next milestone (tracked in `tasks/Big_Picture.txt`), still not wired up here.