meds-algorithm 0.4.0a4__py3-none-any.whl

meds_algorithm/contracts/commands.py

@@ -0,0 +1,182 @@
+"""Derived legacy contract views and compatibility dispatch.
+
+Profile ABCs own lifecycle order; typed requests own argument definitions. These views keep existing
+manifest readers and callers working without maintaining a second specification.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Mapping, Sequence
+from dataclasses import MISSING, dataclass
+from pathlib import Path
+from types import MappingProxyType
+from typing import Any
+
+from ..algorithms import profile_classes, request_type
+from ..artifacts.references import ArtifactReference
+from ..requests import PredictionIndex, TrainingLabels
+from ..tasks.spec import TaskSpec
+from .enums import ArtifactType as ArtifactType
+from .enums import CommandName as CommandName
+
+
+@dataclass(frozen=True)
+class ArtifactInput:
+    """Required upstream envelope; payload format/identity checks remain algorithm-owned."""
+
+    argument: str
+    artifact_type: ArtifactType
+
+
+@dataclass(frozen=True)
+class StepSpec:
+    """Executable boundary specification, independent of the computational backend."""
+
+    artifact_type: ArtifactType
+    output_argument: str
+    artifact_inputs: tuple[ArtifactInput, ...] = ()
+    external_arguments: tuple[str, ...] = ()
+    requires_splits: bool = False
+    label_access: str = "none"
+    task_conditioned: bool = False
+
+    def validate(self, arguments: Mapping[str, Any]) -> None:
+        paths = (
+            self.output_argument,
+            *self.external_arguments,
+            *(item.argument for item in self.artifact_inputs),
+        )
+        for key in paths:
+            value = arguments.get(key)
+            if not isinstance(value, (str, Path)) or not str(value).strip():
+                raise ValueError(f"requires {key}=<path>")
+        if "do_overwrite" in arguments and not isinstance(arguments["do_overwrite"], bool):
+            raise ValueError("do_overwrite must be a boolean")
+        if self.label_access == "none" and "external_labels_dir" in arguments:
+            raise ValueError("use external_index_dir for keys; this step cannot consume training labels")
+        splits = arguments.get("splits")
+        if (self.requires_splits or splits is not None) and (
+            not isinstance(splits, (list, tuple))
+            or not splits
+            or any(not isinstance(s, str) or not s.strip() for s in splits)
+            or len(set(splits)) != len(splits)
+        ):
+            raise ValueError("splits must be an explicit nonempty list of unique split names")
+        if (
+            not self.task_conditioned
+            and "external_task_criteria_file" in arguments
+            and self.label_access != "context_only"
+        ):
+            raise ValueError("this command is task-independent; do not pass external_task_criteria_file")
+
+
+def _step_spec(request):
+    artifacts = []
+    external = []
+    requires_splits = False
+    label_access = "none"
+    task_conditioned = False
+    for field, kind in request.argument_fields():
+        if field.name in ("output", "execution"):
+            continue
+        required = field.default is MISSING and field.default_factory is MISSING
+        if isinstance(kind, type) and issubclass(kind, ArtifactReference):
+            artifacts.append(ArtifactInput(field.metadata["argument"], kind.kind))
+        elif kind is PredictionIndex:
+            external.append("external_index_dir")
+            requires_splits = True
+        elif kind is TrainingLabels:
+            external.append("external_labels_dir")
+            label_access = "train_tuning"
+        elif kind is TaskSpec:
+            external.append("external_task_criteria_file")
+            task_conditioned = True
+        elif field.name == "context":
+            label_access = "context_only"
+        elif required and "argument" in field.metadata:
+            external.append(field.metadata["argument"])
+    return StepSpec(
+        request.result_type.kind,
+        request.output_argument,
+        tuple(artifacts),
+        tuple(external),
+        requires_splits,
+        label_access,
+        task_conditioned,
+    )
+
+
+ALGORITHM_PROFILES = MappingProxyType(
+    {cls.profile: tuple(CommandName(step) for step in cls.steps) for cls in profile_classes()}
+)
+STEP_SPECS = MappingProxyType(
+    {
+        step: _step_spec(request_type(profile, step))
+        for profile, steps in ALGORITHM_PROFILES.items()
+        for step in steps
+    }
+)
+ZERO_SHOT_TASK_COMMANDS = MappingProxyType(
+    {
+        profile: frozenset(step for step in steps if STEP_SPECS[step].task_conditioned)
+        for profile, steps in ALGORITHM_PROFILES.items()
+        if profile.startswith("zero_shot_")
+    }
+)
+
+
+class Command(ABC):
+    """Implement run; dispatch validates argument shapes before invoking algorithm code."""
+
+    name: CommandName
+
+    @abstractmethod
+    def run(self, arguments: Mapping[str, Any]) -> Path:
+        """Validate upstream compatibility, run, and return a published artifact directory."""
+
+    def __call__(self, arguments: Mapping[str, Any]) -> Path:
+        STEP_SPECS[self.name].validate(arguments)
+        return self.run(arguments)
+
+
+class LegacyAlgorithmRepository:
+    """One registry for the union of declared profiles; explicit selection when ambiguous."""
+
+    def __init__(self, profiles: Sequence[str], commands: Mapping[CommandName, type[Command]]) -> None:
+        if isinstance(profiles, str) or not profiles or len(set(profiles)) != len(profiles):
+            raise ValueError("profiles must be a nonempty sequence of unique profile names")
+        unknown = set(profiles) - ALGORITHM_PROFILES.keys()
+        if unknown:
+            raise ValueError(f"Unknown algorithm profiles: {sorted(unknown)}")
+        expected = {command for profile in profiles for command in ALGORITHM_PROFILES[profile]}
+        if set(commands) != expected:
+            raise ValueError(f"Declared profiles require {sorted(expected)}; got {sorted(commands)}")
+        for name, implementation in commands.items():
+            if not isinstance(implementation, type) or not issubclass(implementation, Command):
+                raise TypeError(f"{name} must register a Command subclass")
+            if implementation.name != name:
+                raise ValueError(f"{name} registers a class named {implementation.name}")
+        self.profiles = tuple(profiles)
+        self.commands = dict(commands)
+
+    def select_profile(self, profile: str | None = None) -> str:
+        if profile is None:
+            if len(self.profiles) != 1:
+                raise ValueError("Several profiles are declared; select one with --profile")
+            return self.profiles[0]
+        if profile not in self.profiles:
+            raise ValueError(f"Profile {profile!r} is not declared: {self.profiles}")
+        return profile
+
+    def profile_commands(self, profile: str | None = None) -> tuple[CommandName, ...]:
+        return ALGORITHM_PROFILES[self.select_profile(profile)]
+
+    def run(
+        self, name: CommandName | str, arguments: Mapping[str, Any], *, profile: str | None = None
+    ) -> Path:
+        selected = self.select_profile(profile)
+        command_name = CommandName(name)
+        if command_name not in ALGORITHM_PROFILES[selected]:
+            raise ValueError(f"{command_name.value} is not part of the {selected} algorithm profile")
+        return self.commands[command_name]()(arguments)

meds_algorithm/contracts/enums.py

@@ -0,0 +1,28 @@
+from enum import StrEnum
+
+
+class CommandName(StrEnum):
+    preprocess_data = "preprocess_data"
+    pretrain = "pretrain"
+    train_supervised = "train_supervised"
+    predict_supervised = "predict_supervised"
+    train_finetune = "train_finetune"
+    predict_finetune = "predict_finetune"
+    infer_embeddings = "infer_embeddings"
+    train_probe = "train_probe"
+    predict_probe = "predict_probe"
+    predict_zero_shot_direct = "predict_zero_shot_direct"
+    infer_trajectories = "infer_trajectories"
+    predict_zero_shot_materialized = "predict_zero_shot_materialized"
+    predict_only = "predict_only"
+
+
+class ArtifactType(StrEnum):
+    patients = "patients"
+    pretrained_algorithm = "pretrained_algorithm"
+    embeddings = "embeddings"
+    trajectories = "trajectories"
+    supervised_algorithm = "supervised_algorithm"
+    finetuned_algorithm = "finetuned_algorithm"
+    probe_algorithm = "probe_algorithm"
+    predictions = "predictions"

meds_algorithm/data/__init__.py

@@ -0,0 +1 @@
+"""Dataset boundaries; index projection is separate from access to label values."""

meds_algorithm/data/index.py

@@ -0,0 +1,56 @@
+"""Strict split selection and key-only projection. Requires the optional data extra."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from pathlib import Path
+
+from .validation import INDEX_COLUMNS, validate_keys, validate_splits
+
+
+def split_files(root: Path | str, splits: Sequence[str] | None = None) -> list[Path]:
+    """Select every requested split or fail; never broaden a missing split to all files."""
+    root = Path(root)
+    if isinstance(splits, str):
+        raise TypeError("splits must be a sequence, not a string")
+    if splits is not None:
+        validate_splits(splits)
+    candidates = sorted(root.rglob("*.parquet")) if root.is_dir() else [root]
+    candidates = [p for p in candidates if p.is_file() and p.suffix == ".parquet"]
+    if not candidates:
+        raise FileNotFoundError(f"No parquet index files under {root}")
+    split_names = {"train", "tuning", "held_out", *(splits or ())}
+    for path in candidates:
+        parts = path.relative_to(root).parts[:-1] if root.is_dir() else (root.parent.name,)
+        identities = {path.stem, *parts, *([root.name] if root.is_dir() else [])} & split_names
+        if len(identities) > 1:
+            raise ValueError(f"Ambiguous split identity for {path}: {sorted(identities)}")
+    if splits is None:
+        return candidates
+    selected: set[Path] = set()
+    for split in splits:
+        matches = []
+        for path in candidates:
+            # A single file must also prove which split it represents; its unrelated ancestors do not.
+            parts = path.relative_to(root).parts[:-1] if root.is_dir() else (root.parent.name,)
+            if path.stem == split or split in parts or (root.is_dir() and root.name == split):
+                matches.append(path)
+        if not matches:
+            raise FileNotFoundError(f"No parquet files for requested split {split!r} under {root}")
+        selected.update(matches)
+    return sorted(selected)
+
+
+def read_index(root: Path | str, splits: Sequence[str] | None = None):
+    """Project keys at the Parquet read, never loading label columns into the algorithm boundary."""
+    import polars as pl
+
+    frames = []
+    for path in split_files(root, splits):
+        schema = pl.read_parquet_schema(path)
+        if not all(column in schema for column in INDEX_COLUMNS):
+            raise ValueError(f"Index file {path} is missing required key columns")
+        frames.append(pl.read_parquet(path, columns=list(INDEX_COLUMNS)))
+    index = pl.concat(frames)
+    validate_keys(index, source="requested index")
+    return index

meds_algorithm/data/labels.py

@@ -0,0 +1,55 @@
+"""Explicit training/context targets and strict split-scoped outcome reads."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from .index import read_index, split_files
+from .validation import INDEX_COLUMNS, validate_keys, validate_splits
+
+if TYPE_CHECKING:
+    import polars as pl
+
+
+def read_targets(root: Path | str, splits: Sequence[str], *, allow_unlabelled=False) -> pl.DataFrame | None:
+    import polars as pl
+
+    validate_splits(splits)
+    files = split_files(root, splits)
+    schemas = [pl.read_parquet_schema(path) for path in files]
+    if any(not all(key in schema for key in INDEX_COLUMNS) for schema in schemas):
+        raise ValueError("target files are missing required key columns")
+    labelled = ["boolean_value" in schema for schema in schemas]
+    if not any(labelled) and allow_unlabelled:
+        read_index(root, splits)
+        return None
+    if not all(labelled):
+        raise ValueError("every selected target file must contain boolean_value; mixed schemas are invalid")
+    frame = pl.concat([pl.read_parquet(path, columns=[*INDEX_COLUMNS, "boolean_value"]) for path in files])
+    validate_keys(frame, source="targets")
+    if frame["boolean_value"].dtype != pl.Boolean or frame["boolean_value"].null_count():
+        raise ValueError("boolean_value must contain non-null Boolean outcomes")
+    return frame
+
+
+def read_context_labels(
+    labels_dir: Path | str,
+    context_splits: Sequence[str],
+    evaluated_splits: Sequence[str],
+    *,
+    evaluation_index_dir: Path | str | None = None,
+) -> pl.DataFrame:
+    """Read disjoint labelled context; neither split names nor keys may overlap evaluation."""
+    validate_splits(context_splits)
+    validate_splits(evaluated_splits)
+    if set(context_splits) & set(evaluated_splits):
+        raise ValueError("context splits must be disjoint from evaluated splits")
+    context = read_targets(labels_dir, context_splits)
+    evaluated = read_index(
+        labels_dir if evaluation_index_dir is None else evaluation_index_dir, evaluated_splits
+    )
+    if context.select(INDEX_COLUMNS).join(evaluated, on=list(INDEX_COLUMNS), how="inner").height:
+        raise ValueError("context keys must be disjoint from evaluated keys")
+    return context

meds_algorithm/data/predicates.py

@@ -0,0 +1,60 @@
+"""Compose feature predicates without overriding the dataset's definitions."""
+
+import hashlib
+from pathlib import Path
+
+import yaml
+
+RESOLVED_PREDICATES_FILENAME = "resolved_feature_predicates.yaml"
+
+
+class _UniqueKeysLoader(yaml.SafeLoader):
+    def construct_mapping(self, node, deep=False):
+        self.flatten_mapping(node)
+        mapping = {}
+        for key_node, value_node in node.value:
+            key = self.construct_object(key_node, deep=deep)
+            if not isinstance(key, str) or not key.strip():
+                raise ValueError("Predicate YAML keys must be nonempty strings")
+            if key in mapping:
+                raise ValueError(f"Duplicate YAML key: {key}")
+            mapping[key] = self.construct_object(value_node, deep=deep)
+        return mapping
+
+
+def _digest(data: bytes) -> str:
+    return "sha256:" + hashlib.sha256(data).hexdigest()
+
+
+def _read(path: Path):
+    data = path.read_bytes()
+    try:
+        document = yaml.load(data, Loader=_UniqueKeysLoader)
+    except yaml.YAMLError as error:
+        raise ValueError(f"Invalid predicates YAML in {path}: {error}") from error
+    if not isinstance(document, dict) or set(document) != {"predicates"}:
+        raise ValueError(f"{path} must contain only a predicates mapping, not task/cohort configuration")
+    predicates = document["predicates"]
+    if not isinstance(predicates, dict) or any(
+        not isinstance(definition, dict) or not definition for definition in predicates.values()
+    ):
+        raise ValueError(f"{path} predicates must map names to nonempty definitions")
+    return predicates, {"path": str(path.resolve()), "digest": _digest(data)}
+
+
+def compose_feature_predicates(base: Path | None, additional: Path) -> tuple[bytes, dict]:
+    """Return deterministic YAML and provenance from the same source snapshots.
+
+    Accept predicate-only documents in MEDS-DEV's shape. Reject duplicate names even when definitions
+    agree. Expression semantics and dataset compatibility remain the algorithm's responsibility.
+    """
+    predicates, base_source = ({}, None) if base is None else _read(Path(base))
+    additions, additional_source = _read(Path(additional))
+    if duplicates := predicates.keys() & additions.keys():
+        raise ValueError(f"Additional predicates duplicate dataset names: {sorted(duplicates)}")
+    content = yaml.safe_dump({"predicates": predicates | additions}, sort_keys=True).encode("utf-8")
+    return content, {
+        "base": base_source,
+        "additional": additional_source,
+        "resolved": {"path": RESOLVED_PREDICATES_FILENAME, "digest": _digest(content)},
+    }

meds_algorithm/data/validation.py

@@ -0,0 +1,25 @@
+"""Shared key and split validation without importing a dataframe engine at module import."""
+
+from collections.abc import Sequence
+
+INDEX_COLUMNS = ("subject_id", "prediction_time")
+
+
+def validate_splits(splits: Sequence[str]) -> None:
+    if (
+        isinstance(splits, str)
+        or not isinstance(splits, Sequence)
+        or not splits
+        or any(not isinstance(s, str) or not s.strip() for s in splits)
+        or len(set(splits)) != len(splits)
+    ):
+        raise ValueError("splits must be a nonempty sequence of unique nonblank names")
+
+
+def validate_keys(frame, *, source="index") -> None:
+    if not all(column in frame.columns for column in INDEX_COLUMNS):
+        raise ValueError(f"{source} is missing required key columns")
+    if any(frame[column].null_count() for column in INDEX_COLUMNS):
+        raise ValueError(f"{source} contains null keys")
+    if frame.select(INDEX_COLUMNS).unique().height != frame.height:
+        raise ValueError(f"{source} contains duplicate keys")

meds_algorithm/evaluation/__init__.py

@@ -0,0 +1 @@
+"""Keyed prediction validation and post-score truth attachment."""

meds_algorithm/evaluation/predictions.py

@@ -0,0 +1,56 @@
+"""Keyed probabilities and post-score ground-truth attachment."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from ..data.labels import read_targets
+from ..data.validation import INDEX_COLUMNS, validate_keys
+
+if TYPE_CHECKING:
+    import polars as pl
+PREDICTED_PROBABILITY = "predicted_boolean_probability"
+
+
+def check_decoded(index: pl.DataFrame, predictions: pl.DataFrame) -> pl.DataFrame:
+    """Require unique, non-null matching keys and finite probabilities in [0, 1]."""
+    import polars as pl
+
+    validate_keys(index, source="requested index")
+    validate_keys(predictions, source="decoded predictions")
+    keys = list(INDEX_COLUMNS)
+    missing = index.select(keys).join(predictions.select(keys), on=keys, how="anti")
+    extra = predictions.select(keys).join(index.select(keys), on=keys, how="anti")
+    if missing.height or extra.height:
+        raise ValueError(f"decoded predictions miss {missing.height} and add {extra.height} requested keys")
+    if PREDICTED_PROBABILITY not in predictions.columns:
+        raise ValueError(f"decoded predictions lack {PREDICTED_PROBABILITY}")
+    values = predictions[PREDICTED_PROBABILITY]
+    if (
+        values.dtype not in (pl.Float32, pl.Float64)
+        or values.null_count()
+        or not values.is_finite().all()
+        or not values.is_between(0.0, 1.0).all()
+    ):
+        raise ValueError(f"{PREDICTED_PROBABILITY} must be a finite non-null probability in [0, 1]")
+    return predictions
+
+
+def attach_ground_truth(
+    predictions: pl.DataFrame, labels_dir: Path | str, splits: Sequence[str]
+) -> pl.DataFrame:
+    """Join truth only after scores are fixed; an entirely unlabelled index is supported.
+
+    This function cannot enforce when the caller scores. Its result must never feed back into
+    preprocessing, algorithm fitting, selection or scoring. Missing splits/mixed label schemas fail.
+    """
+    validate_keys(predictions, source="predictions")
+    labels = read_targets(labels_dir, splits, allow_unlabelled=True)
+    if labels is None:
+        return predictions
+    joined = predictions.drop("boolean_value", strict=False).join(labels, on=list(INDEX_COLUMNS), how="left")
+    if joined.height != predictions.height or joined["boolean_value"].null_count():
+        raise ValueError("every prediction key must have exactly one ground-truth label")
+    return joined

meds_algorithm/integrations/__init__.py

@@ -0,0 +1 @@
+"""Repository registration and external runner adapters."""

meds_algorithm/integrations/meds_dev.py

@@ -0,0 +1,51 @@
+"""Install this repository's descriptor into a MEDS-DEV checkout."""
+
+from __future__ import annotations
+
+import argparse
+import re
+import shutil
+from pathlib import Path
+
+from ..artifacts.publication import staged_directory
+
+
+def register(repo: Path, meds_dev: Path, name: str, profile: str | None = None) -> Path:
+    source = repo.resolve()
+    descriptors = {p.parent.name: p for p in (source / "algorithms").glob("*/model.yaml")}
+    if profile is None:
+        if len(descriptors) != 1:
+            raise ValueError("Select --profile when the repository has several descriptors")
+        profile = next(iter(descriptors))
+    if profile not in descriptors:
+        raise ValueError(f"No descriptor for {profile!r}; available: {sorted(descriptors)}")
+    if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9_-]*", name):
+        raise ValueError("name must be a single alphanumeric, underscore or hyphen identifier")
+    target = meds_dev.resolve() / "src" / "MEDS_DEV" / "models" / f"{name}__{profile}"
+    if not target.parent.is_dir():
+        raise FileNotFoundError(f"{meds_dev} has no src/MEDS_DEV/models directory")
+    requirements = (source / "requirements.txt").read_text()
+    # A file URL needs no quoting: uv reads quotes in requirement files literally, and pip splits on spaces.
+    requirements = (
+        "\n".join(
+            f"-e {source.as_uri()}" if line.strip() == "-e ." else line for line in requirements.splitlines()
+        )
+        + "\n"
+    )
+    with staged_directory(target) as staging:
+        shutil.copy2(descriptors[profile], staging / "model.yaml")
+        (staging / "requirements.txt").write_text(requirements)
+        predicates = source / "predicates.yaml"
+        if predicates.is_file():
+            shutil.copy2(predicates, staging / "predicates.yaml")
+    return target
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--meds-dev", type=Path, required=True)
+    parser.add_argument("--repo", type=Path, default=Path.cwd())
+    parser.add_argument("--name", required=True)
+    parser.add_argument("--profile")
+    args = parser.parse_args()
+    print(register(args.repo, args.meds_dev, args.name, args.profile))