ms-cql-sdk 0.1.0__py3-none-any.whl

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__"]

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",
+]

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."""

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."""

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

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."""

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

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."""

cql_sdk/api.py

@@ -0,0 +1,80 @@
+"""High-level convenience facade for the cql-sdk package.
+
+This module is the preferred public entry point for most users. It delegates
+to :mod:`cql_sdk.invocation.toolkit` but offers a minimal, explicit surface
+so consumers never have to touch lower-level modules such as
+:mod:`cql_sdk.compiler` or :mod:`cql_sdk.runtime`.
+
+Typical workflow::
+
+    from cql_sdk.api import load_library, invoke
+
+    lib = load_library("HelloWorld.elm.json")
+    result = invoke(lib, definition="Greeting")
+
+For repeated invocations or more advanced wiring (custom terminology, FHIR
+retrieval, caching), use :class:`cql_sdk.invocation.toolkit.InvocationToolkit`
+directly.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from cql_sdk.elm.models.library import Library
+from cql_sdk.elm.serialization.loader import load_library_from_path, load_library_from_string
+from cql_sdk.invocation.toolkit import InvocationToolkit
+from cql_sdk.runtime.context import RuntimeContext
+
+__all__ = [
+    "create_context",
+    "invoke",
+    "load_library",
+    "load_library_from_text",
+]
+
+
+def load_library(path: str | Path) -> Library:
+    """Load an ELM library from a JSON file on disk."""
+    return load_library_from_path(Path(path))
+
+
+def load_library_from_text(text: str) -> Library:
+    """Load an ELM library from a JSON string."""
+    return load_library_from_string(text)
+
+
+def create_context(**overrides: Any) -> RuntimeContext:
+    """Build a default :class:`RuntimeContext` with optional overrides."""
+    return RuntimeContext.default(**overrides)
+
+
+def invoke(
+    library: Library,
+    *,
+    definition: str,
+    parameters: dict[str, Any] | None = None,
+    context: RuntimeContext | None = None,
+) -> Any:
+    """Invoke a named definition on a loaded library.
+
+    Args:
+        library: A previously loaded ELM library.
+        definition: Name of the ``def`` (or function) to evaluate.
+        parameters: Optional parameter bindings.
+        context: Optional pre-built runtime context; a default one is
+            created if omitted.
+
+    Returns:
+        The evaluated result. For scalar definitions this is typically a
+        Python primitive; for list-valued definitions a list is returned.
+    """
+    toolkit = InvocationToolkit()
+    toolkit.register(library)
+    return toolkit.invoke(
+        library_identifier=library.identifier,
+        definition=definition,
+        parameters=parameters,
+        context=context,
+    )

cql_sdk/cli/__init__.py

@@ -0,0 +1,5 @@
+"""Typer-based CLI, exposed as the ``cql-sdk`` console script."""
+
+from cql_sdk.cli.main import app
+
+__all__ = ["app"]

cql_sdk/cli/commands/__init__.py

@@ -0,0 +1 @@
+"""CLI subcommands."""

cql_sdk/cli/commands/inspect.py

@@ -0,0 +1,32 @@
+"""``cql-sdk inspect`` command."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from cql_sdk.elm.serialization.loader import load_library_from_path
+
+
+def inspect(elm_file: Path = typer.Argument(..., exists=True, readable=True)) -> None:
+    library = load_library_from_path(elm_file)
+    console = Console()
+
+    console.print(f"[bold]Library:[/bold] {library.identifier}")
+    if library.includes:
+        console.print(f"[bold]Includes:[/bold] {', '.join(str(i) for i in library.includes)}")
+
+    table = Table(title="Definitions", show_lines=False)
+    table.add_column("Name")
+    table.add_column("Access")
+    table.add_column("Context")
+    table.add_column("Expression type")
+    for name, d in library.definitions.items():
+        table.add_row(name, d.access_level, d.context or "-", d.expression.type or "-")
+    console.print(table)
+
+    if library.parameters:
+        console.print(f"[bold]Parameters:[/bold] {', '.join(library.parameters)}")

cql_sdk/cli/commands/package.py

@@ -0,0 +1,20 @@
+"""``cql-sdk package`` command."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+from cql_sdk.packaging.library_package import LibraryPackage
+
+
+def package(
+    input_dir: Path = typer.Argument(..., exists=True, file_okay=False, readable=True),
+    output: Path = typer.Option(..., "--output", "-o", help="Output directory for the package."),
+    name: str | None = typer.Option(None, "--name", help="Override the package name."),
+) -> None:
+    pkg = LibraryPackage.discover(input_dir, name=name)
+    target = pkg.write(output)
+    Console().print(f"[green]Packaged[/green] {pkg.manifest.name} -> {target}")

cql_sdk/cli/commands/run.py

@@ -0,0 +1,47 @@
+"""``cql-sdk run`` command."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+from cql_sdk.elm.serialization.loader import load_library_from_path
+from cql_sdk.fhir.context import context_from_bundle
+from cql_sdk.invocation.toolkit import InvocationToolkit
+
+
+def run(
+    elm_file: Path = typer.Argument(..., exists=True, readable=True),
+    definition: str = typer.Option(..., "--definition", "-d", help="Definition name to evaluate."),
+    bundle: Path | None = typer.Option(
+        None, "--bundle", help="Optional FHIR Bundle JSON to bind as the data source."
+    ),
+) -> None:
+    library = load_library_from_path(elm_file)
+    toolkit = InvocationToolkit()
+    toolkit.register(library)
+
+    context = None
+    if bundle is not None:
+        bundle_obj = json.loads(bundle.read_text(encoding="utf-8"))
+        context = context_from_bundle(bundle_obj)
+
+    result = toolkit.invoke(
+        library_identifier=library.identifier,
+        definition=definition,
+        context=context,
+    )
+    Console().print_json(data={"definition": definition, "result": _json_safe(result)})
+
+
+def _json_safe(value: object) -> object:
+    if isinstance(value, (str, int, float, bool)) or value is None:
+        return value
+    if isinstance(value, list):
+        return [_json_safe(v) for v in value]
+    if isinstance(value, dict):
+        return {k: _json_safe(v) for k, v in value.items()}
+    return repr(value)

cql_sdk/cli/commands/validate.py

@@ -0,0 +1,28 @@
+"""``cql-sdk validate`` command."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+from cql_sdk.elm.serialization.loader import load_library_from_path
+from cql_sdk.invocation.toolkit import InvocationToolkit
+
+
+def validate(elm_file: Path = typer.Argument(..., exists=True, readable=True)) -> None:
+    library = load_library_from_path(elm_file)
+    toolkit = InvocationToolkit()
+    toolkit.register(library)
+    missing = toolkit.validate(library.identifier)
+
+    console = Console()
+    if not missing:
+        console.print(f"[green]OK[/green] - all ELM nodes in {library.identifier} are executable.")
+        raise typer.Exit(code=0)
+
+    console.print(f"[yellow]Warning[/yellow] - {len(missing)} unsupported ELM node type(s):")
+    for t in sorted(missing):
+        console.print(f"  - {t}")
+    raise typer.Exit(code=1)

cql_sdk/cli/main.py

@@ -0,0 +1,38 @@
+"""Top-level ``cql-sdk`` Typer application."""
+
+from __future__ import annotations
+
+import typer
+
+from cql_sdk.cli.commands import inspect as inspect_cmd
+from cql_sdk.cli.commands import package as package_cmd
+from cql_sdk.cli.commands import run as run_cmd
+from cql_sdk.cli.commands import validate as validate_cmd
+from cql_sdk.version import __version__
+
+app = typer.Typer(
+    name="cql-sdk",
+    help="Command-line tools for the cql-sdk Python package.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+app.command("inspect", help="Print a human-readable summary of an ELM file.")(inspect_cmd.inspect)
+app.command("validate", help="Validate operator coverage for an ELM file.")(validate_cmd.validate)
+app.command("run", help="Evaluate a named definition in an ELM file.")(run_cmd.run)
+app.command("package", help="Package an input directory of ELM/resources.")(package_cmd.package)
+
+
+@app.callback()
+def _root(
+    version: bool = typer.Option(
+        False, "--version", help="Show the cql-sdk version and exit.", is_eager=True
+    ),
+) -> None:
+    if version:
+        typer.echo(__version__)
+        raise typer.Exit()
+
+
+if __name__ == "__main__":  # pragma: no cover
+    app()

cql_sdk/compiler/__init__.py

@@ -0,0 +1,7 @@
+"""Compiler / planning layer.
+
+This layer bridges ELM nodes to executable runtime behavior. In the initial
+scaffold the runtime interprets ELM directly; the planner is kept as a
+seam so a future version can pre-bake expression trees into compiled
+callables without changing the public API.
+"""

cql_sdk/compiler/bindings.py

@@ -0,0 +1,14 @@
+"""Bindings between ELM nodes and operator callables (future expansion)."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class Binding:
+    """Pairs an ELM node type name with a compiled callable."""
+
+    elm_type: str
+    callable_: Callable[..., object]

cql_sdk/compiler/expression_builder.py

@@ -0,0 +1,23 @@
+"""Placeholder for an expression builder that compiles ELM into Python callables."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from cql_sdk.elm.models.base import ElmNode
+    from cql_sdk.runtime.context import RuntimeContext
+
+
+def build(expression: ElmNode) -> Callable[[RuntimeContext], Any]:
+    """Return a callable that evaluates ``expression`` against a context.
+
+    The current implementation simply wraps :meth:`RuntimeContext.evaluate`;
+    a future version may inline/specialize expression trees here.
+    """
+
+    def _run(ctx: RuntimeContext) -> Any:
+        return ctx.evaluate(expression)
+
+    return _run

cql_sdk/compiler/planner.py

@@ -0,0 +1,37 @@
+"""Expression planner: walks ELM and verifies operator coverage up front."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from cql_sdk.elm.models.base import ElmNode
+
+if TYPE_CHECKING:
+    from cql_sdk.abstractions.operators import OperatorRegistry
+    from cql_sdk.elm.models.library import Library
+
+
+def missing_operators(library: Library, registry: OperatorRegistry) -> set[str]:
+    """Return ELM node types referenced by ``library`` but absent from ``registry``.
+
+    Useful as a fail-fast validation step before attempting execution.
+    """
+    missing: set[str] = set()
+    for definition in library.definitions.values():
+        _walk(definition.expression, registry, missing)
+    return missing
+
+
+def _walk(node: ElmNode, registry: OperatorRegistry, missing: set[str]) -> None:
+    if node.type and not registry.has(node.type):
+        missing.add(node.type)
+    for value in node.payload.values():
+        _walk_value(value, registry, missing)
+
+
+def _walk_value(value: object, registry: OperatorRegistry, missing: set[str]) -> None:
+    if isinstance(value, dict) and "type" in value:
+        _walk(ElmNode.from_json(value), registry, missing)
+    elif isinstance(value, list):
+        for item in value:
+            _walk_value(item, registry, missing)

cql_sdk/compiler/type_manager.py

@@ -0,0 +1,18 @@
+"""ELM type-name -> Python type management."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass(slots=True)
+class TypeManager:
+    """Very small registry mapping ELM type names to Python constructors."""
+
+    mapping: dict[str, type] = field(default_factory=dict)
+
+    def register(self, elm_type: str, py_type: type) -> None:
+        self.mapping[elm_type] = py_type
+
+    def resolve(self, elm_type: str) -> type | None:
+        return self.mapping.get(elm_type)

cql_sdk/elm/__init__.py

@@ -0,0 +1,5 @@
+"""ELM (Expression Logical Model) data types and serialization."""
+
+from cql_sdk.elm.models.library import Library
+
+__all__ = ["Library"]

cql_sdk/elm/models/__init__.py

@@ -0,0 +1 @@
+"""ELM model classes."""

cql_sdk/elm/models/base.py

@@ -0,0 +1,35 @@
+"""Common base types for ELM model classes.
+
+The scaffold intentionally uses a loose representation: every ELM expression
+is captured as an :class:`ElmNode` holding its discriminator ``type`` plus
+the raw payload. This preserves fidelity with the JSON representation and
+lets the planner grow rich, typed models over time without requiring a full
+schema port up front.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(slots=True)
+class ElmNode:
+    """A raw ELM expression node.
+
+    Attributes:
+        type: The ELM discriminator (e.g. ``"Literal"``, ``"FunctionRef"``).
+        payload: The full JSON object for this node, as produced by the
+            CQL-to-ELM translator.
+    """
+
+    type: str
+    payload: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_json(cls, obj: dict[str, Any]) -> ElmNode:
+        # ELM JSON uses "type" to encode the node discriminator.
+        return cls(type=str(obj.get("type", "")), payload=obj)
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return self.payload.get(key, default)

cql_sdk/elm/models/expressions.py

@@ -0,0 +1,17 @@
+"""Typed helpers around common ELM expression shapes."""
+
+from __future__ import annotations
+
+from cql_sdk.elm.models.base import ElmNode
+
+
+def is_literal(node: ElmNode) -> bool:
+    return node.type == "Literal"
+
+
+def literal_value(node: ElmNode) -> str | None:
+    return node.get("value")
+
+
+def literal_value_type(node: ElmNode) -> str | None:
+    return node.get("valueType")

cql_sdk/elm/models/library.py

@@ -0,0 +1,52 @@
+"""ELM :class:`Library` model — the top-level artifact produced by CQL-to-ELM."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from cql_sdk.elm.models.base import ElmNode
+
+
+@dataclass(slots=True)
+class LibraryIdentifier:
+    id: str
+    version: str | None = None
+
+    def __str__(self) -> str:
+        return f"{self.id}" + (f"|{self.version}" if self.version else "")
+
+
+@dataclass(slots=True)
+class LibraryDefinition:
+    """A single named `def` or `function` inside a library."""
+
+    name: str
+    expression: ElmNode
+    access_level: str = "Public"
+    context: str | None = None
+
+
+@dataclass(slots=True)
+class Library:
+    """An ELM library: the loaded, parsed form of a ``.elm.json`` file."""
+
+    identifier: LibraryIdentifier
+    definitions: dict[str, LibraryDefinition] = field(default_factory=dict)
+    parameters: dict[str, ElmNode] = field(default_factory=dict)
+    includes: list[LibraryIdentifier] = field(default_factory=list)
+    value_sets: dict[str, dict[str, Any]] = field(default_factory=dict)
+    code_systems: dict[str, dict[str, Any]] = field(default_factory=dict)
+    raw: dict[str, Any] = field(default_factory=dict)
+    """The original parsed JSON, preserved for pass-through scenarios."""
+
+    def has_definition(self, name: str) -> bool:
+        return name in self.definitions
+
+    def get_definition(self, name: str) -> LibraryDefinition:
+        try:
+            return self.definitions[name]
+        except KeyError as exc:
+            raise KeyError(
+                f"Definition '{name}' not found in library '{self.identifier}'."
+            ) from exc