microsoft/azure-healthcare-digital-quality-cql-sdk

microsoft/azure-healthcare-digital-quality-cql-sdk

Language: Python

License: NOASSERTION

Stars: 0

Forks: 0

Open issues: 3

Created: 2026-06-01T15:24:48Z

Pushed: 2026-06-01T15:48:37Z

Default branch: main

Fork: no

Archived: no

README:

cql-sdk

> Install from PyPI: `pip install ms-cql-sdk` > > Published at . The Python import name remains cql_sdk.

A modular Python SDK for working with Clinical Quality Language (CQL) and its compiled form ELM (Expression Logical Model). Inspired by the layering of the Firely C# CQL SDK, but designed idiomatically for Python and for modern data platforms (standalone, containers, PySpark, Microsoft Fabric).

> Status: early scaffold. The architecture, public API surface and extension > points are deliberately sketched so they can grow toward a fuller CQL > engine without breaking consumers.

Disclaimer

This SDK is provided as-is under the Apache-2.0 license. It is a general purpose CQL/ELM execution toolkit and does not include or grant any rights to third-party measure specifications, value sets, or code systems.

If you use this SDK to compute HEDIS® measures in production, you are responsible for obtaining the appropriate license from NCQA. HEDIS is a registered trademark of the National Committee for Quality Assurance (NCQA). See for measure licensing terms.

The same applies to other proprietary measure stewards (for example, CMS eCQM artifacts may have their own usage terms, and any LOINC, SNOMED CT, RxNorm, ICD, or CPT content carries its own licensing).

What's new in 0.4.2

• Project URL metadata now points at the canonical

github.com/microsoft/azure-healthcare-digital-quality-cql-sdk repository.

• Added Disclaimer section covering HEDIS® / NCQA licensing

responsibilities for production use, and a note on third-party terminology content (LOINC, SNOMED CT, RxNorm, ICD, CPT).

What's new in 0.4.1

• README: surface the 0.3.0 and 0.4.0 release notes on the PyPI project

page (no code changes).

What's new in 0.4.0

• Spark adapter fix: SparkInvocation.run now uses the library

registered via from_elm_path instead of the first entry in the toolkit registry, which was the auto-registered synthetic FHIRHelpers. Fixes KeyError: "Definition '' not found in library 'FHIRHelpers|4.0.1'.".

• SparkInvocation accepts an explicit default_library_identifier for

callers constructing the toolkit directly.

What's new in 0.3.0

• Invocation toolkit auto-registers a synthetic FHIRHelpers library so

measures that include FHIRHelpers resolve without an extra step.

• Public API consolidation around InvocationToolkit (register, has,

validate, invoke) as the preferred entry point.

• Library registry de-duplicates id and id|version keys during

iteration.

What's new in 0.2.1

• Internal: ruff and mypy --strict are now both clean (parser/translator

refactors broke long lines into helpers, no behavior change). Aligns the package with the CI gates so downstream forks pass on a clean checkout.

What's new in 0.2.0

• Pure-Python CQL → ELM front end under

[cql_sdk.compiler.cql_to_elm](src/cql_sdk/compiler/cql_to_elm/) — no Java required. Covers the CQL 1.5 subset used by typical CMS eCQM measures: library/using/include/codesystem/valueset/code/parameter/context/define, retrieves and queries with where/sort/return, all standard arithmetic and comparison operators, interval/list literals, casts, and fluent function calls (X.extension("...")).

• New public API: cql_sdk.api.load_library_from_cql and

load_library_from_cql_text.

• New CLI command: cql-sdk compile [--output ELM.json].

Why this SDK

• Pure-Python core for ELM loading, runtime context, operators, invocation.
• Optional FHIR integration (retrieval, type conversion, terminology).
• Optional Spark / Microsoft Fabric integration (the *same* core package

runs unchanged in both environments).

• A Typer-based CLI for inspecting, validating, packaging and running ELM.
• Designed around *pre-generated ELM artifacts* as a first-class workflow —

no Java/CQL-to-ELM toolchain is required for normal execution.

Package layering

cql_sdk
├── abstractions/ # Protocols / ABCs for operators, terminology, data, packaging
├── elm/ # ELM model + (de)serialization
├── runtime/ # RuntimeContext, operators, comparers, intervals, datetime
├── compiler/ # Expression planner, bindings, type manager
├── invocation/ # High-level toolkit / invoker / library registry (PUBLIC API)
├── fhir/ # Optional FHIR adapters
├── spark/ # Optional Spark / Fabric adapters
├── packaging/ # Library + resource packaging primitives
├── cli/ # Typer CLI (`cql-sdk`)
└── api.py # Top-level convenience facade (PUBLIC API)

The invocation toolkit and [cql_sdk.api](src/cql_sdk/api.py) are the preferred entry points. Internal modules (compiler, low-level runtime) are available but not the recommended consumption path.

Quick start

Install (base)

uv sync

Install with optional extras

uv sync --extra fhir
uv sync --extra spark # pulls pyspark; not required for base install
uv sync --extra dev --extra test

Run the local hello-world example

uv run python examples/hello_world/run.py

Load ELM and invoke a definition (Python)

from cql_sdk.api import load_library, invoke

library = load_library("examples/hello_world/HelloWorld.elm.json")
result = invoke(library, definition="Greeting")
print(result)

Compile a CQL source file (no Java required)

from cql_sdk.api import load_library_from_cql

library = load_library_from_cql("path/to/Measure.cql")
print(library.identifier) # CMS122|11
print(list(library.definitions)) # ['Initial Population', 'Numerator', ...]

Or get the raw ELM JSON via the lower-level entry point:

from cql_sdk.compiler.cql_to_elm import compile_file
elm = compile_file("path/to/Measure.cql")

Use the CLI

uv run cql-sdk compile path/to/Measure.cql --output dist/Measure.elm.json
uv run cql-sdk inspect examples/hello_world/HelloWorld.elm.json
uv run cql-sdk validate examples/hello_world/HelloWorld.elm.json
uv run cql-sdk run examples/hello_world/HelloWorld.elm.json --definition Greeting
uv run cql-sdk package examples/hello_world --output dist/packages

Spark / Fabric usage

Spark support is *opt-in*:

uv sync --extra spark

from pyspark.sql import SparkSession
from…