Metadata-Version: 2.4
Name: ms-cql-sdk
Version: 0.2.1
Summary: Modular Python CQL SDK (ELM loading, runtime, invocation, FHIR and Spark adapters).
Project-URL: Homepage, https://github.com/ctava-msft/azure-healthcare-digital-quality-cql-sdk
Project-URL: Documentation, https://github.com/ctava-msft/azure-healthcare-digital-quality-cql-sdk#readme
Project-URL: Source, https://github.com/ctava-msft/azure-healthcare-digital-quality-cql-sdk
Project-URL: Issues, https://github.com/ctava-msft/azure-healthcare-digital-quality-cql-sdk/issues
Author: cql-sdk authors
License:                                  Apache License
                                   Version 2.0, January 2004
                                http://www.apache.org/licenses/
        
        Copyright (c) 2026 cql-sdk authors
        
        Licensed under the Apache License, Version 2.0 (the "License");
        you may not use this file except in compliance with the License.
        You may obtain a copy of the License at
        
            http://www.apache.org/licenses/LICENSE-2.0
        
        Unless required by applicable law or agreed to in writing, software
        distributed under the License is distributed on an "AS IS" BASIS,
        WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
        See the License for the specific language governing permissions and
        limitations under the License.
License-File: LICENSE
Keywords: cql,elm,fhir,healthcare,quality-measures
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Healthcare Industry
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Requires-Python: >=3.12
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: 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 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.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

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

```bash
uv sync
```

### Install with optional extras

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

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

### 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

Apache-2.0. See [LICENSE](LICENSE).
