Metadata-Version: 2.5
Name: ms-cql-sdk
Version: 0.7.0
Summary: Compile and execute Clinical Quality Language on PostgreSQL-backed FHIR data.
Project-URL: Homepage, https://github.com/microsoft/azure-healthcare-digital-quality-cql-sdk
Project-URL: Documentation, https://github.com/microsoft/azure-healthcare-digital-quality-cql-sdk#readme
Project-URL: Source, https://github.com/microsoft/azure-healthcare-digital-quality-cql-sdk
Project-URL: Issues, https://github.com/microsoft/azure-healthcare-digital-quality-cql-sdk/issues
Author: cql-sdk authors
License:     MIT License
        
            Copyright (c) Microsoft Corporation.
        
            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
License-File: LICENSE
Keywords: cql,elm,fhir,healthcare,postgresql,quality-measures,sql
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Healthcare Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Requires-Python: >=3.11
Requires-Dist: pydantic>=2.7
Requires-Dist: python-dateutil>=2.9
Requires-Dist: rich>=13.7
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: pre-commit>=3.7; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocs>=1.6; extra == 'docs'
Provides-Extra: fhir
Requires-Dist: fhir-resources>=7.1; extra == 'fhir'
Provides-Extra: postgres
Requires-Dist: pg8000>=1.31; extra == 'postgres'
Provides-Extra: spark
Requires-Dist: pyspark>=3.5; extra == 'spark'
Provides-Extra: test
Requires-Dist: pytest-cov>=5.0; extra == 'test'
Requires-Dist: pytest-xdist>=3.6; extra == 'test'
Requires-Dist: pytest>=8.2; extra == 'test'
Description-Content-Type: text/markdown

# 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 Python SDK that compiles **Clinical Quality Language (CQL)** definitions to
parameterized PostgreSQL SQL and executes them over FHIR R4 resources stored
as JSONB. ELM remains an internal compiler representation and a compatibility
surface for existing consumers.

## What's new in 0.7.0

- `PostgresCompiler` translates CQL/ELM definitions to parameterized SQL.
- `PostgresExecutor` runs definitions against PostgreSQL 16.
- `PostgresFHIRStore` initializes the FHIR JSONB schema, atomically replaces
  patient Bundles, and loads the bundled expanded ValueSets.
- All definitions in the platform's CMS122v11, CMS165v9, and ePC-02 measures
  compile and execute as SQL.
- The prior in-memory Python ELM runtime remains available for compatibility.

## Disclaimer

This SDK is provided as-is under the MIT 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&reg;** 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 <https://www.ncqa.org/hedis/measures/> 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.6.1

- README: surface the 0.6.0 release notes on the PyPI project page (no
  code changes).

## What's new in 0.6.0

- **Expanded CQL → ELM front-end** for parity with common Firely CQL SDK
  constructs:
  - `DateTime` literals with timezone offsets (`Z`, `+hh:mm`, `-hh:mm`).
  - The `X between low and high` range operator.
  - Conditional expressions: `if ... then ... else ...` and
    `case ... when ... then ... [else ...] end`.
  - `duration in <precision> between` and
    `difference in <precision> between`.
  - Model-qualified cast types such as `X as FHIR.dateTime`.
  - Function-call forms `Exists(...)`, `Now()`, `Today()`.
- Runtime additions: `Now`, `Today`, `DurationBetween` and
  `DifferenceBetween` operators, plus case-insensitive `as` coercion for
  FHIR primitive types.

## What's new in 0.5.0

- **DQM (FHIR / QI-Core) measure package evaluation** via the new
  [`cql_sdk.dqm`](src/cql_sdk/dqm) package: a FHIR `Measure` resource model,
  QI-Core profile model-info, an ELM-first multi-library `MeasurePackage`
  loader, and proportion scoring for both patient (`boolean`) and
  episode-of-care (`Encounter`) basis.
- Runtime additions: list set operations (`Union` / `Except` / `Intersect`),
  value-set membership (`InValueSet` / `AnyInValueSet`), user-defined function
  parameter binding (`OperandRef`), and query `with` / `without` relationships.
- New public API: `load_measure_package` / `evaluate_measure_package`.

## What's new in 0.4.3

- License changed from Apache-2.0 to MIT.
- Added Origins and Attribution, Acknowledgements, and Relationship to Firely CQL SDK sections to README.

## 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&reg; / 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 '<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`](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 <CQL_FILE> [--output ELM.json]`.

## Why this SDK

- PostgreSQL-native execution for set-based clinical quality evaluation.
- Parameterized SQL over an indexed FHIR JSONB and terminology schema.
- Pure-Python CQL parser with ELM used as an internal intermediate form.
- 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
 ├── postgres/       # CQL-to-SQL compiler, executor, schema, and FHIR store
 ├── 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)

```bash
uv sync
```

### Install with optional extras

```bash
uv sync --extra fhir
uv sync --extra postgres   # pulls pg8000; required for PostgreSQL execution
uv sync --extra spark        # pulls pyspark; not required for base install
uv sync --extra dev --extra test
```

### Run the local hello-world example

```bash
uv run python examples/hello_world/run.py
```

### Load ELM and invoke a definition (Python)

```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)

```python
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:

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

### Execute CQL on PostgreSQL

```python
from cql_sdk.api import execute_library_on_postgres, load_library_from_cql
from cql_sdk.postgres import PostgresFHIRStore

database_url = "postgresql://dq@localhost:5432/dq"
# Set PGPASSWORD through the process environment or a secret provider.
store = PostgresFHIRStore(database_url=database_url)
store.initialize()
store.load_value_sets()
store.replace_patient_bundle("patient-1", bundle)

library = load_library_from_cql("path/to/Measure.cql")
result = execute_library_on_postgres(
  library,
  definition="Initial Population",
  database_url=database_url,
  patient_id="patient-1",
  parameters={"Measurement Period": (period_start, period_end)},
)
```

Use `compile_cql_to_sql(...)` when SQL generation is needed without execution.
All literal values, patient identifiers, JSON paths, and terminology values
are emitted as bind parameters.

### Use the CLI

```bash
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*:

```bash
uv sync --extra spark
```

```python
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

```bash
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](docs/development.md) for more.

## Documentation

- [Architecture](docs/architecture.md)
- [Public API](docs/public-api.md)
- [Packaging](docs/packaging.md)
- [Development](docs/development.md)

## License

MIT. See [LICENSE](LICENSE).

This license covers the SDK source code only. It does **not** grant rights
to HEDIS&reg; measure specifications (license from NCQA required for
production use, see the [Disclaimer](#disclaimer) section), nor to any
third-party terminology content (LOINC, SNOMED CT, RxNorm, ICD, CPT, etc.).

## Origins and Attribution

This project was inspired by and derived from concepts demonstrated in the Firely and NCQA CQL SDK project:

- <https://github.com/FirelyTeam/firely-cql-sdk>

The Firely CQL SDK is NCQA's and Firely's official SDK for working with Clinical Quality Language (CQL) on the .NET platform.

The Microsoft Azure Healthcare Digital Quality CQL SDK extends these concepts to support additional healthcare analytics scenarios, including cloud-native execution patterns, Python interoperability, Spark/Fabric integration, and Azure-based deployment models.

We are grateful to Firely and NCQA for their contributions to the CQL ecosystem and for advancing interoperable clinical quality measurement technologies.

The original Firely project and its contributors retain ownership of their respective intellectual property and code contributions. Please refer to the upstream repository for additional details and licensing information.

## Relationship to Firely CQL SDK

This project is not a drop-in replacement for the Firely CQL SDK.

While portions of the architecture, compiler design concepts, and CQL execution patterns were informed by the Firely implementation, this SDK introduces additional capabilities focused on analytics, distributed execution, cloud-native deployment, and modern healthcare data platform integration.

## Acknowledgements

Special thanks to:

- Firely
- NCQA
- HL7 Clinical Quality Language (CQL) Community
- FHIR Community Contributors

for advancing standards-based clinical quality measurement and interoperability.
