ms-cql-sdk 0.4.1

Modular Python CQL SDK (ELM loading, runtime, invocation, FHIR and Spark adapters).

cql-sdk

Install from PyPI: pip install ms-cql-sdk

Published at https://pypi.org/project/ms-cql-sdk/. 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.

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 '<name>' 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 — 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 <CQL_FILE> [--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 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 cql_sdk.spark import SparkInvocation

spark = SparkSession.builder.getOrCreate()
invocation = SparkInvocation.from_elm_path(
    "examples/hello_world/HelloWorld.elm.json", spark=spark
)
df = invocation.run(definition="Greeting")
df.show()

Core modules never import pyspark — importing cql_sdk.spark is the only place Spark is required.

Development

uv sync --extra dev --extra test
uv run ruff check .
uv run mypy
uv run pytest -m "not spark"
uv run pytest -m spark            # requires `--extra spark`

See docs/development.md for more.

Documentation

• Architecture
• Public API
• Packaging
• Development

License

Apache-2.0. See LICENSE.