ms-cql-sdk 0.1.0__tar.gz

ms_cql_sdk-0.1.0/.gitignore

@@ -0,0 +1,45 @@
+# Byte-compiled / cache
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.token
+# Build artifacts
+build/
+dist/
+*.egg-info/
+.eggs/
+.wheels/
+
+# Virtual envs
+.venv/
+venv/
+env/
+
+# uv / pip
+.uv/
+pip-wheel-metadata/
+
+# Tests / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+.mypy_cache/
+.ruff_cache/
+
+# IDEs
+.idea/
+.vscode/
+*.swp
+.DS_Store
+
+# Docs build
+site/
+
+# Local data
+*.log
+.cache/
+.tmp/
+.history

ms_cql_sdk-0.1.0/LICENSE

@@ -0,0 +1,17 @@
+                                 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.

ms_cql_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,185 @@
+Metadata-Version: 2.4
+Name: ms-cql-sdk
+Version: 0.1.0
+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
+
+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.
+
+## 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)
+```
+
+### Use the CLI
+
+```bash
+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).

ms_cql_sdk-0.1.0/README.md

@@ -0,0 +1,127 @@
+# 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.
+
+## 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)
+```
+
+### Use the CLI
+
+```bash
+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).

ms_cql_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,137 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ms-cql-sdk"
+version = "0.1.0"
+description = "Modular Python CQL SDK (ELM loading, runtime, invocation, FHIR and Spark adapters)."
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.12"
+authors = [{ name = "cql-sdk authors" }]
+keywords = ["cql", "elm", "fhir", "healthcare", "quality-measures"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Healthcare Industry",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Medical Science Apps.",
+]
+dependencies = [
+    "typer>=0.12",
+    "rich>=13.7",
+    "pydantic>=2.7",
+    "python-dateutil>=2.9",
+]
+
+[project.optional-dependencies]
+fhir = [
+    "fhir.resources>=7.1",
+]
+spark = [
+    "pyspark>=3.5",
+]
+dev = [
+    "ruff>=0.6",
+    "mypy>=1.11",
+    "build>=1.2",
+    "pre-commit>=3.7",
+]
+test = [
+    "pytest>=8.2",
+    "pytest-cov>=5.0",
+    "pytest-xdist>=3.6",
+]
+docs = [
+    "mkdocs>=1.6",
+    "mkdocs-material>=9.5",
+]
+
+[project.scripts]
+cql-sdk = "cql_sdk.cli.main:app"
+
+[project.urls]
+Homepage = "https://github.com/ctava-msft/azure-healthcare-digital-quality-cql-sdk"
+Documentation = "https://github.com/ctava-msft/azure-healthcare-digital-quality-cql-sdk#readme"
+Source = "https://github.com/ctava-msft/azure-healthcare-digital-quality-cql-sdk"
+Issues = "https://github.com/ctava-msft/azure-healthcare-digital-quality-cql-sdk/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cql_sdk"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "README.md", "LICENSE", "pyproject.toml"]
+
+# -------- Tooling --------
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = [
+    "E", "F", "W",      # pycodestyle + pyflakes
+    "I",                 # isort
+    "B",                 # bugbear
+    "UP",                # pyupgrade
+    "SIM",               # simplify
+    "RUF",               # ruff rules
+    "D",                 # pydocstyle
+    "TID",               # tidy-imports
+]
+ignore = [
+    "D100", "D101", "D102", "D103", "D104", "D105", "D106", "D107",
+    "D203", "D213",
+    "B008",  # Typer uses call-in-default as its canonical pattern
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["D", "E501"]
+"examples/**" = ["D"]
+"src/cql_sdk/elm/serialization/loader.py" = ["E501"]
+"src/cql_sdk/packaging/library_package.py" = ["E501"]
+"src/cql_sdk/spark/session.py" = ["E501"]
+"src/cql_sdk/runtime/context.py" = ["E501"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+warn_unused_ignores = true
+warn_redundant_casts = true
+warn_unreachable = true
+disallow_untyped_defs = true
+no_implicit_optional = true
+files = ["src"]
+
+[[tool.mypy.overrides]]
+module = ["pyspark.*", "fhir.resources.*"]
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+minversion = "8.0"
+addopts = "-ra --strict-markers --strict-config"
+testpaths = ["tests"]
+markers = [
+    "unit: fast, isolated unit tests",
+    "integration: end-to-end ELM loading / invocation tests",
+    "spark: requires pyspark (install with `uv sync --extra spark`)",
+]
+filterwarnings = [
+    "error",
+    "ignore::DeprecationWarning:pyspark.*",
+]
+
+[tool.coverage.run]
+branch = true
+source = ["cql_sdk"]
+
+[tool.coverage.report]
+show_missing = true
+skip_empty = true

ms_cql_sdk-0.1.0/src/cql_sdk/__init__.py

@@ -0,0 +1,10 @@
+"""cql-sdk: a modular Python SDK for CQL/ELM execution.
+
+Public entry points live in :mod:`cql_sdk.api` and
+:mod:`cql_sdk.invocation.toolkit`. Everything else is considered internal
+and may evolve without notice.
+"""
+
+from cql_sdk.version import __version__
+
+__all__ = ["__version__"]

ms_cql_sdk-0.1.0/src/cql_sdk/abstractions/__init__.py

@@ -0,0 +1,21 @@
+"""Abstractions: protocols and ABCs describing stable SDK seams.
+
+Concrete implementations live under :mod:`cql_sdk.runtime`,
+:mod:`cql_sdk.fhir`, :mod:`cql_sdk.spark`, and :mod:`cql_sdk.packaging`.
+"""
+
+from cql_sdk.abstractions.data_source import DataSource
+from cql_sdk.abstractions.invocation import Invoker
+from cql_sdk.abstractions.operators import OperatorRegistry
+from cql_sdk.abstractions.packaging import PackageWriter
+from cql_sdk.abstractions.terminology import TerminologyProvider
+from cql_sdk.abstractions.type_conversion import TypeConverter
+
+__all__ = [
+    "DataSource",
+    "Invoker",
+    "OperatorRegistry",
+    "PackageWriter",
+    "TerminologyProvider",
+    "TypeConverter",
+]

ms_cql_sdk-0.1.0/src/cql_sdk/abstractions/data_source.py

@@ -0,0 +1,27 @@
+"""Data source protocol used by retrieve-style ELM nodes."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class DataSource(Protocol):
+    """Abstract source of clinical/patient data.
+
+    Implementations may be backed by in-memory FHIR bundles, file-based
+    fixtures, REST FHIR servers, or Spark DataFrames.
+    """
+
+    def retrieve(
+        self,
+        *,
+        data_type: str,
+        code_property: str | None = None,
+        codes: Iterable[Any] | None = None,
+        date_property: str | None = None,
+        date_range: Any | None = None,
+        context: Any | None = None,
+    ) -> Iterable[Any]:
+        """Retrieve resources/records matching the given criteria."""

ms_cql_sdk-0.1.0/src/cql_sdk/abstractions/invocation.py

@@ -0,0 +1,20 @@
+"""Invocation protocol — the top-level user-facing seam."""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class Invoker(Protocol):
+    """Executes a named definition on a registered library."""
+
+    def invoke(
+        self,
+        *,
+        library_identifier: str,
+        definition: str,
+        parameters: dict[str, Any] | None = None,
+        context: Any | None = None,
+    ) -> Any:
+        """Evaluate ``definition`` in the given library and return its value."""

ms_cql_sdk-0.1.0/src/cql_sdk/abstractions/operators.py

@@ -0,0 +1,31 @@
+"""Operator registry protocol.
+
+An operator registry maps ELM operator/expression node *type names* to
+executable Python callables. Keeping this behind a Protocol lets the runtime,
+FHIR, and Spark layers swap or extend operator behavior without touching
+core planner/invoker code.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+OperatorFn = Any  # Callable[[RuntimeContext, ElmNode, ...], Any] — kept loose to avoid cycles
+
+
+@runtime_checkable
+class OperatorRegistry(Protocol):
+    """Maps ELM node type names to executable operator callables."""
+
+    def register(self, elm_type: str, fn: OperatorFn) -> None:
+        """Register (or replace) an operator implementation."""
+
+    def get(self, elm_type: str) -> OperatorFn:
+        """Return the operator callable for ``elm_type``.
+
+        Raises:
+            KeyError: if no operator is registered for ``elm_type``.
+        """
+
+    def has(self, elm_type: str) -> bool:
+        """Return whether an operator is registered for ``elm_type``."""

ms_cql_sdk-0.1.0/src/cql_sdk/abstractions/packaging.py

@@ -0,0 +1,14 @@
+"""Packaging seam for emitting library/manifest/resource artifacts."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class PackageWriter(Protocol):
+    """Writes a logical package (ELM + resources + manifest) to disk."""
+
+    def write(self, *, output_dir: Path, manifest: Any, resources: list[Any]) -> Path:
+        """Persist the package and return the root output path."""

ms_cql_sdk-0.1.0/src/cql_sdk/abstractions/terminology.py

@@ -0,0 +1,31 @@
+"""Terminology provider protocol (value sets, code systems, concepts)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol, runtime_checkable
+
+
+@dataclass(frozen=True, slots=True)
+class Code:
+    code: str
+    system: str | None = None
+    display: str | None = None
+    version: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ValueSetRef:
+    id: str
+    version: str | None = None
+
+
+@runtime_checkable
+class TerminologyProvider(Protocol):
+    """Resolves value set membership and code system lookups."""
+
+    def expand(self, value_set: ValueSetRef) -> list[Code]:
+        """Return the expansion (list of codes) for a value set."""
+
+    def in_value_set(self, code: Code, value_set: ValueSetRef) -> bool:
+        """Return whether ``code`` is a member of ``value_set``."""

ms_cql_sdk-0.1.0/src/cql_sdk/abstractions/type_conversion.py

@@ -0,0 +1,16 @@
+"""Type conversion seam between ELM/CQL types and host Python values."""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class TypeConverter(Protocol):
+    """Bidirectional conversion between CQL/ELM values and Python values."""
+
+    def to_python(self, cql_value: Any, *, cql_type: str | None = None) -> Any:
+        """Convert a CQL/ELM value to an idiomatic Python value."""
+
+    def to_cql(self, py_value: Any, *, cql_type: str | None = None) -> Any:
+        """Convert a Python value into the representation expected by ELM."""