meds-algorithm 0.4.0a4__tar.gz → 0.4.0a5__tar.gz

{meds_algorithm-0.4.0a4 → meds_algorithm-0.4.0a5}/.github/workflows/ci.yml

@@ -20,6 +20,8 @@ jobs:
       - run: uv run ruff check .
       - run: uv run ruff format --check .
       - run: uv run pytest -q
+      - name: Test at the declared polars floor (algorithms may pin old polars)
+        run: uv run --with 'polars==1.0.0' pytest -q
       - run: uv build
       - name: Validate distribution metadata and PyPI README rendering
         run: uvx --from 'twine>=6' twine check --strict dist/*
@@ -31,9 +33,10 @@ jobs:
       - name: Run conformance tests against the installed wheel outside the checkout
         run: |
           wheel=$(realpath dist/*.whl)
-          uv pip install --python /tmp/core-wheel/bin/python "${wheel}[conformance]"
+          uv pip install --python /tmp/core-wheel/bin/python "${wheel}[conformance,orchestration]"
           uv pip check --python /tmp/core-wheel/bin/python
           cp -r tests /tmp/core-wheel-tests
+          cp pyproject.toml /tmp/core-wheel-tests/
           cd /tmp
           /tmp/core-wheel/bin/python -I -m pytest -q /tmp/core-wheel-tests
   windows-wheel:

{meds_algorithm-0.4.0a4 → meds_algorithm-0.4.0a5}/ARCHITECTURE.md

@@ -66,15 +66,27 @@ classDiagram
 Each profile class declares its `profile` and ordered `steps`; method annotations identify request
 types. Request fields define CLI arguments, while each request declares its output argument and
 result artifact class. There is no independent step-definition registry. `ALGORITHM_PROFILES` and
-`STEP_SPECS` are read-only, derived compatibility views for existing consumers.
+`STEP_SPECS` are read-only views derived from these classes. `StepSpec.from_request_type` constructs
+a specification for manifest validation and command inspection without maintaining a second definition.
 
-## Requests, configuration and artifacts
+## Algorithm configuration
+
+Configuration answers **how this algorithm behaves**. A request answers **what one invocation reads
+and writes**. An artifact reference identifies **persisted data or fitted state**. These are separate
+objects; sharing serialization does not make them one hierarchy.
+
+The algorithm instance owns its configuration. Hyperparameters belong here, not in step requests.
+`ExecutionOptions` belongs to each request and holds the invocation's seed and overwrite policy.
 
 ```mermaid
 classDiagram
+    class Algorithm {
+        <<abstract>>
+        config: AlgorithmConfig
+    }
     class AlgorithmConfig {
         <<frozen dataclass>>
-        additional_predicates_file
+        additional_predicates_file: Path optional
         validate()
         from_dict(values)
         from_file(path)
@@ -87,74 +99,22 @@ classDiagram
     }
     class NNConfig {
         <<frozen dataclass>>
-        capacity
-        learning_rate
-        batch_size
-        weight_decay
-        dropout
+        capacity: float
+        learning_rate: float
+        batch_size: int
+        weight_decay: float
+        dropout: float
     }
     class AlgorithmOwnedNNConfig {
         <<frozen dataclass>>
         architecture-specific defaults and settings
     }
-    class StepRequest {
-        <<frozen dataclass>>
-        output
-        execution
-        predicates_file
-        from_arguments(arguments)
-        save(path)
-        load(path)
-    }
-    class PredictSupervisedRequest {
-        data
-        algorithm
-        index
-    }
-    class ArtifactReference {
-        <<frozen dataclass>>
-        directory
-        kind
-        open(directory)
-        read_manifest()
-    }
-    class PreparedDataArtifact
-    class SupervisedAlgorithmArtifact
-    class PredictionsArtifact
-    class PredictionIndex {
-        directory
-        splits
-        read()
-    }
-    class ArtifactDestination {
-        directory
-    }
-    class ExecutionOptions {
-        seed
-        overwrite
-    }
+    Algorithm --> AlgorithmConfig : config
     AlgorithmConfig <|-- AlgorithmOwnedConfig
     AlgorithmConfig <|-- NNConfig
     NNConfig <|-- AlgorithmOwnedNNConfig
-    StepRequest <|-- PredictSupervisedRequest
-    ArtifactReference <|-- PreparedDataArtifact
-    ArtifactReference <|-- SupervisedAlgorithmArtifact
-    ArtifactReference <|-- PredictionsArtifact
-    PredictSupervisedRequest --> PreparedDataArtifact : data
-    PredictSupervisedRequest --> SupervisedAlgorithmArtifact : algorithm
-    PredictSupervisedRequest --> PredictionIndex : index
-    StepRequest --> ArtifactDestination : output
-    StepRequest --> ExecutionOptions : execution
 ```
 
-Artifact constructors normalize paths without loading payloads. `open`/`read_manifest` validate the
-common envelope and artifact type. The runner validates references before algorithm code. Payload readers
-remain algorithm-owned; core imposes no tensor, tokenizer, batching or dataframe representation.
-
-`TrainingLabels.read` accepts only train/tuning. `PredictionIndex.read` projects keys at the I/O boundary.
-`PredictionContext` explicitly selects train/tuning and checks overlap with evaluated keys. Zero-shot
-requests carry `TaskSpec`. These interfaces make permissions clear; they are not a filesystem sandbox.
-
 Define configuration in the algorithm repository:
 
 ```python
@@ -304,6 +264,233 @@ interface covers configuration and its existing persisted provenance; it does no
 or count network parameters. Avoid adding another dataset-selection configuration until its upstream
 owner and identity format are agreed.
 
+## Step requests: typed method parameters
+
+A request is an immutable **parameter object** for one method call. Its concrete type defines the
+required inputs, optional inputs and output destination. The children represent different operations;
+a preprocessing request does not turn into a training request. Every method has a concrete annotation,
+for example `predict_supervised(request: PredictSupervisedRequest) -> PayloadMetadata`.
+
+`StepRequest` supplies these common fields and methods to **all 13 concrete requests**:
+
+```mermaid
+classDiagram
+    class StepRequest {
+        <<frozen dataclass>>
+        output: ArtifactDestination
+        execution: ExecutionOptions
+        predicates_file: Path optional
+        from_arguments(arguments)
+        artifact_inputs()
+        save(path)
+        load(path)
+    }
+    class ArtifactDestination {
+        directory: Path
+    }
+    class ExecutionOptions {
+        seed: int = 0
+        overwrite: bool = false
+    }
+    StepRequest --> ArtifactDestination : output
+    StepRequest --> ExecutionOptions : execution
+```
+
+Callers instantiate concrete requests. `output_argument` and `result_type` are class metadata used to
+map CLI arguments and construct the resulting artifact reference; they are not caller-supplied fields.
+The following diagrams show every concrete request, split for readability. Each inherits the common
+fields above. Relationships are inheritance (hollow arrow) or references to other objects (plain arrow).
+
+### Preprocessing and training requests
+
+```mermaid
+classDiagram
+    StepRequest <|-- PreprocessDataRequest
+    StepRequest <|-- PretrainRequest
+    StepRequest <|-- TrainSupervisedRequest
+    StepRequest <|-- TrainFinetuneRequest
+    StepRequest <|-- TrainProbeRequest
+    class PreprocessDataRequest {
+        meds_dir: Path
+        result_type: PreparedDataArtifact
+    }
+    class PretrainRequest {
+        data: PreparedDataArtifact
+        result_type: PretrainedAlgorithmArtifact
+    }
+    class TrainSupervisedRequest {
+        data: PreparedDataArtifact
+        labels: TrainingLabels
+        result_type: SupervisedAlgorithmArtifact
+    }
+    class TrainFinetuneRequest {
+        data: PreparedDataArtifact
+        pretrained: PretrainedAlgorithmArtifact
+        labels: TrainingLabels
+        result_type: FinetunedAlgorithmArtifact
+    }
+    class TrainProbeRequest {
+        embeddings: EmbeddingsArtifact
+        labels: TrainingLabels
+        result_type: ProbeAlgorithmArtifact
+    }
+```
+
+### Embedding inference and fitted prediction requests
+
+```mermaid
+classDiagram
+    StepRequest <|-- InferEmbeddingsRequest
+    StepRequest <|-- PredictSupervisedRequest
+    StepRequest <|-- PredictFinetuneRequest
+    StepRequest <|-- PredictProbeRequest
+    class InferEmbeddingsRequest {
+        data: PreparedDataArtifact
+        pretrained: PretrainedAlgorithmArtifact
+        index: PredictionIndex
+        result_type: EmbeddingsArtifact
+    }
+    class PredictSupervisedRequest {
+        data: PreparedDataArtifact
+        fitted_algorithm: SupervisedAlgorithmArtifact
+        index: PredictionIndex
+        result_type: PredictionsArtifact
+    }
+    class PredictFinetuneRequest {
+        data: PreparedDataArtifact
+        fitted_algorithm: FinetunedAlgorithmArtifact
+        index: PredictionIndex
+        result_type: PredictionsArtifact
+    }
+    class PredictProbeRequest {
+        embeddings: EmbeddingsArtifact
+        fitted_algorithm: ProbeAlgorithmArtifact
+        index: PredictionIndex
+        result_type: PredictionsArtifact
+    }
+```
+
+`fitted_algorithm` references saved fitted state; it is not the Python algorithm instance. The CLI
+names remain `input_supervised_algorithm_dir`, `input_finetuned_algorithm_dir` and
+`input_probe_algorithm_dir`. These three requests use serialization schema version 2; version 1
+request envelopes with the old `algorithm` field are rejected rather than silently reinterpreted.
+
+### Trajectory inference, zero-shot and predict-only requests
+
+```mermaid
+classDiagram
+    StepRequest <|-- InferTrajectoriesRequest
+    StepRequest <|-- PredictZeroShotDirectRequest
+    StepRequest <|-- PredictZeroShotMaterializedRequest
+    StepRequest <|-- PredictOnlyRequest
+    class InferTrajectoriesRequest {
+        data: PreparedDataArtifact
+        pretrained: PretrainedAlgorithmArtifact
+        index: PredictionIndex
+        result_type: TrajectoriesArtifact
+    }
+    class PredictZeroShotDirectRequest {
+        data: PreparedDataArtifact
+        pretrained: PretrainedAlgorithmArtifact
+        index: PredictionIndex
+        task: TaskSpec
+        result_type: PredictionsArtifact
+    }
+    class PredictZeroShotMaterializedRequest {
+        data: PreparedDataArtifact
+        trajectories: TrajectoriesArtifact
+        meds_dir: Path
+        index: PredictionIndex
+        task: TaskSpec
+        result_type: PredictionsArtifact
+    }
+    class PredictOnlyRequest {
+        data: PreparedDataArtifact
+        index: PredictionIndex
+        context: PredictionContext optional
+        task: TaskSpec optional
+        result_type: PredictionsArtifact
+    }
+```
+
+`TrainingLabels.read` accepts only train/tuning. `PredictionIndex.read` projects keys at the I/O boundary.
+`PredictionContext` explicitly selects train/tuning and checks overlap with evaluated keys. Zero-shot
+requests carry `TaskSpec`. These interfaces make permitted inputs clear; they are not a filesystem sandbox.
+All requests inherit optional `predicates_file`; preprocessing uses feature predicates and zero-shot
+prediction uses task predicates. Inference has no training-label field. Evaluation truth is a runner-only
+argument and never enters a prediction request.
+
+### Constructing and executing a request
+
+Given an implemented `MyAlgorithm(SupervisedAlgorithm)` and its `MyAlgorithmConfig`, a caller uses:
+
+```python
+from pathlib import Path
+from meds_algorithm import (
+    ArtifactDestination,
+    PreparedDataArtifact,
+    StepRunner,
+    SupervisedAlgorithmArtifact,
+)
+from meds_algorithm.requests import PredictionIndex, PredictSupervisedRequest
+
+algorithm = MyAlgorithm(MyAlgorithmConfig())  # implementation and its hyperparameters
+request = PredictSupervisedRequest(
+    data=PreparedDataArtifact(Path("prepared")),
+    fitted_algorithm=SupervisedAlgorithmArtifact(Path("trained")),
+    index=PredictionIndex(Path("index"), ("held_out",)),
+    output=ArtifactDestination(Path("predictions")),
+)
+predictions = StepRunner().run(
+    algorithm,
+    "predict_supervised",
+    request,
+    profile="supervised",
+)
+```
+
+Required keyword fields, type validation and semantic checks make the method boundary explicit. Frozen
+requests cannot be modified in place. The runner substitutes a private staging destination in a copy;
+the algorithm writes to `request.output.directory`. Configuration remains on `algorithm.config`.
+Both objects are persisted separately as `config.json` and `request.json` for reproducibility.
+
+## Artifact references and outputs
+
+Artifacts are persisted results shared between independent invocations. References identify their
+directory and expected kind; they do not hold a loaded neural network or preprocessing payload.
+
+```mermaid
+classDiagram
+    class ArtifactReference {
+        <<frozen dataclass>>
+        directory: Path
+        kind: ArtifactType
+        open(directory)
+        read_manifest()
+    }
+    ArtifactReference <|-- PreparedDataArtifact
+    ArtifactReference <|-- PretrainedAlgorithmArtifact
+    ArtifactReference <|-- SupervisedAlgorithmArtifact
+    ArtifactReference <|-- FinetunedAlgorithmArtifact
+    ArtifactReference <|-- ProbeAlgorithmArtifact
+    ArtifactReference <|-- EmbeddingsArtifact
+    ArtifactReference <|-- TrajectoriesArtifact
+    ArtifactReference <|-- PredictionsArtifact
+    class PayloadMetadata {
+        format: str
+        version: int = 1
+    }
+    PredictSupervisedRequest --> PreparedDataArtifact : data
+    PredictSupervisedRequest --> SupervisedAlgorithmArtifact : fitted_algorithm
+    PredictSupervisedRequest --> PredictionIndex : index
+```
+
+Constructors normalize paths without loading payloads. `open`/`read_manifest` validate the common
+envelope and artifact type. The runner validates references before algorithm code. Payload readers
+remain algorithm-owned; core imposes no tensor, tokenizer, batching or dataframe representation.
+Methods return `PayloadMetadata` describing what they wrote. The runner returns the published typed
+artifact reference; metadata and the reference are different objects.
+
 ## Shared execution
 
 `AlgorithmRepository` associates profile names with implementation classes, creates a fresh instance
@@ -338,7 +525,7 @@ sequenceDiagram
 Algorithm methods write payloads only into `request.output.directory` and return `PayloadMetadata`. They
 must not write the reserved `manifest.yaml`, `config.json` or `request.json`, or publish final directories.
 Directly calling algorithm methods bypasses runner validation/publication; production and test adapters
-must use the runner. Low-level publication helpers remain available for legacy implementations.
+must use the runner. The runner uses low-level publication helpers internally.
 
 Prediction payloads are Parquet shards with keys and probabilities, without ground truth. The runner
 validates their combined key set and probabilities, then optionally attaches evaluation labels. That
@@ -369,8 +556,81 @@ Replaying evaluation additionally requires the runner-only label path recorded i
 | Template | Algorithm/config stubs, CLI, profile YAML, test adapters and operational files |
 | Algorithm repository | Concrete typed config, algorithms/components, payload formats, compatibility and scientific tests |
 
-Legacy `Command`/`LegacyAlgorithmRepository` retain their previous mapping-based behavior. They do not acquire
-the runner's stronger validation/publication automatically. New generated repositories use
-`AlgorithmRepository`. Contract version 4 uses algorithm-named package imports, CLI entry points,
-artifact types and input/output arguments. Version 3 artifacts and serialized types are not accepted
-under the new names by changing a version field. Existing repositories require an explicit migration.
+`AlgorithmRepository` is the only repository dispatcher. It constructs typed requests and delegates
+to `StepRunner`; the former mapping-based command dispatcher has been removed. Fitted inputs must
+record the complete resolved configuration; the default validator does not fill missing historical fields.
+Contract version 4 uses algorithm-named package imports, CLI entry points, artifact types and arguments.
+Existing repositories and incompatible serialized requests require an explicit migration.
+
+## Classes and functional helpers
+
+Objects own meaningful responsibilities: algorithms own configuration and implementation methods,
+requests own typed invocation parameters, references own artifact identity, and the runner owns execution.
+`StepSpec.from_request_type` is a class factory because its purpose is to construct a specification.
+
+Small stateless operations such as file hashing, encoding/decoding and conformance assertions remain
+functions. `staged_directory` and `measured_artifact` are context managers: their local state exists only
+between entry and exit, with cleanup and rollback on failure. A class wrapping these functions would
+not improve their current lifecycle. `_ProcessTreeMemorySampler` is a class because it manages a
+background sampler with start/stop state. The design does not require every function to become a method.
+
+## Shared acceptance tests
+
+The optional `meds-algorithm[conformance]` extra supplies `AlgorithmConformanceTests`.
+A generated test class inherits its eight tests; ordinary pytest fixtures connect the suite to a
+concrete repository. No production algorithm inherits from the testing classes.
+
+```mermaid
+classDiagram
+    class AlgorithmConformanceTests
+    class TestConformance
+    class AlgorithmCase {
+        root: Path
+        name: str
+        configurations: Sequence[AlgorithmConfig]
+        stub_profiles: Set[str]
+        profiles: tuple[str, ...]
+        create_repository() AlgorithmRepository
+        run_e2e() E2EResult
+        fitted_codes() Set[str]
+        prepare_meds_dev_run() MEDSDevRun
+    }
+    AlgorithmConformanceTests <|-- TestConformance
+    AlgorithmConformanceTests ..> AlgorithmCase : algorithm_case fixture
+    AlgorithmCase ..> AlgorithmRepository : factory derives profiles
+    AlgorithmCase ..> AlgorithmConfig : representative configurations
+    AlgorithmCase ..> E2EResult : execution adapter
+    AlgorithmCase ..> MEDSDevRun : integration adapter
+```
+
+The generated `profile` fixture parametrizes registered profiles. `AlgorithmCase` only describes
+inputs/adapters; it does not execute training or persist fitted state. `ProfileRunner` and
+`MEDSDevPreparer` are callable typing protocols, not additional required implementation base classes.
+Scientific tests and payload inspection stay in the algorithm repository. Shared test behavior and
+its canonical inventory live in the packaged `TESTING.md`, rendered by the template documentation.
+
+## Profile orchestration (prototype)
+
+The optional orchestration layer runs above the unchanged typed execution boundary. `RunConfig`
+is a Hydra input schema; the concrete algorithm Config remains authoritative for algorithm settings.
+`RunPlanner` derives artifact wiring from `StepSpec`/request types and validates before creating outputs.
+
+```mermaid
+classDiagram
+    RunPlanner ..> RunConfig : resolves
+    RunPlanner --> RunPlan : creates without writing
+    RunPlan *-- StagePlan
+    RunCoordinator ..> RunPlan : persists
+    RunCoordinator --> LocalExecution
+    RunCoordinator --> SubmititExecution
+    LocalExecution ..> StageJob
+    SubmititExecution ..> StageJob : submits with dependencies
+    StageJob ..> AlgorithmRepository : invokes existing CLI in fresh process
+    AlgorithmRepository --> StepRunner
+```
+
+A `StageJob` contains resolved CLI arguments and paths, never a fitted algorithm object.
+Local execution waits for each subprocess; SLURM submits the chain and returns a job-ID receipt.
+The same `RunPlan` is printed by dry-run or executed. Scheduling settings are persisted in `plan.json`,
+while algorithm configs/requests remain in each artifact manifest. The bundled `ORCHESTRATION.md`
+describes supported inputs, resource settings and limitations; the template embeds that same guide.

meds_algorithm-0.4.0a4/README.md → meds_algorithm-0.4.0a5/PKG-INFO

@@ -1,7 +1,36 @@
+Metadata-Version: 2.5
+Name: meds-algorithm
+Version: 0.4.0a5
+Summary: Shared MEDS algorithm contracts and conformance boundaries.
+Project-URL: Repository, https://github.com/McDermottHealthAI/meds-algorithm
+Project-URL: Documentation, https://github.com/McDermottHealthAI/meds-algorithm/blob/main/ARCHITECTURE.md
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: pyyaml>=6
+Provides-Extra: conformance
+Requires-Dist: meds-evaluation==0.0.3; extra == 'conformance'
+Requires-Dist: polars>=1; extra == 'conformance'
+Requires-Dist: pyarrow>=15; extra == 'conformance'
+Requires-Dist: pytest>=8; extra == 'conformance'
+Provides-Extra: data
+Requires-Dist: polars>=1; extra == 'data'
+Provides-Extra: orchestration
+Requires-Dist: hydra-core<1.4,>=1.3.2; extra == 'orchestration'
+Requires-Dist: submitit<2,>=1.5.2; extra == 'orchestration'
+Provides-Extra: test
+Requires-Dist: hydra-core<1.4,>=1.3.2; extra == 'test'
+Requires-Dist: meds-evaluation==0.0.3; extra == 'test'
+Requires-Dist: polars>=1; extra == 'test'
+Requires-Dist: pyarrow>=15; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Requires-Dist: submitit<2,>=1.5.2; extra == 'test'
+Description-Content-Type: text/markdown
+
 # meds-algorithm
 
 [![Python 3.11+](https://img.shields.io/badge/Python-3.11%2B-blue?logo=python&logoColor=white)](https://www.python.org/downloads/)
-[![PyPI: unreleased](https://img.shields.io/badge/PyPI-unreleased-lightgrey)](https://github.com/McDermottHealthAI/meds-algorithm/blob/main/RELEASING.md)
+[![PyPI](https://img.shields.io/pypi/v/meds-algorithm)](https://pypi.org/project/meds-algorithm/)
 [![Tests and code quality](https://github.com/McDermottHealthAI/meds-algorithm/actions/workflows/ci.yml/badge.svg)](https://github.com/McDermottHealthAI/meds-algorithm/actions/workflows/ci.yml)
 [![Documentation](https://img.shields.io/badge/docs-architecture-blue)](https://github.com/McDermottHealthAI/meds-algorithm/blob/main/ARCHITECTURE.md)
 [![Contributors](https://img.shields.io/github/contributors/McDermottHealthAI/meds-algorithm)](https://github.com/McDermottHealthAI/meds-algorithm/graphs/contributors)
@@ -29,7 +58,8 @@ src/meds_algorithm/
 ├── configuration.py            # AlgorithmConfig, NNConfig and execution options
 ├── serialization.py            # strict, versioned config/request JSON serialization
 ├── runner.py                   # validate, execute, measure, publish; CLI adapter
-├── contracts/commands.py       # derived compatibility views and legacy dispatch
+├── orchestration/              # optional Hydra planning, local subprocesses and Submitit jobs
+├── contracts/commands.py       # derived step specifications and validation
 ├── artifacts/
 │   ├── references.py           # lazy typed artifact references and payload metadata
 │   ├── manifest.py             # measured artifacts, envelope reading and digests
@@ -50,13 +80,13 @@ src/meds_algorithm/
 
 ## Installation and dependencies
 
-Install a reviewed revision with
-`pip install 'meds-algorithm @ git+https://github.com/McDermottHealthAI/meds-algorithm.git@<full-commit-sha>'`.
-The template currently records the exact SHA. For package-index release checks and publishing setup,
+Install from PyPI with `pip install 'meds-algorithm[data]'`. Pin a released version in algorithm
+repositories for reproducible environments. For package-index release checks and publishing setup,
 see the [release guide](https://github.com/McDermottHealthAI/meds-algorithm/blob/main/RELEASING.md).
 
 - Base package: PyYAML; no dataframe engine, test runner, GPU or algorithm framework is imported by base APIs.
 - `data` extra: Polars for index/target reads and prediction validation.
+- `orchestration` extra: Hydra configuration and Submitit; see the [prototype runner guide](src/meds_algorithm/ORCHESTRATION.md).
 - `conformance` extra: pytest, Polars, PyArrow and the pinned MEDS evaluation schema implementation.
 - `test` extra: dependencies for developing and testing this package.
 
@@ -91,8 +121,7 @@ layout into that interface; these upstream names are not part of this package's
 
 ## Publication, provenance and measurement
 
-Pass the algorithm checkout explicitly to `StepRunner(repo=algorithm_root)` or, for legacy implementations,
-`measured_artifact(..., repo=algorithm_root)`. The package never
+Pass the algorithm checkout explicitly to `StepRunner(repo=algorithm_root)`. The package never
 infers the algorithm from its own installation path or the working directory. Without a supplied checkout,
 commit and dirty state are unknown (`null`); wheel deployments must retain algorithm build provenance
 separately rather than inventing a checkout revision.
@@ -112,6 +141,8 @@ values as `null`. GPU instrumentation remains the algorithm/framework's responsi
 
 ## Validation
 
+See [the test catalogue](src/meds_algorithm/TESTING.md) for what each test checks, why it exists, and the limits of the suite.
+
 ```bash
 uv sync --extra test --group dev
 uv run ruff check .
@@ -132,6 +163,21 @@ training. Keep each algorithm's data-access and cluster approval rules in its ow
 
 ## Changes
 
+### 0.4.0a5 (2026-11-03)
+
+- Add an optional profile-runner prototype: shared Hydra schema, resolved dry-run plans, local
+  subprocess execution and dependent Submitit SLURM jobs. Existing per-step APIs remain unchanged.
+
+- Ship an opt-in `AlgorithmConformanceTests` acceptance suite and typed `AlgorithmCase` adapter;
+  generated repositories inherit the checks and retain algorithm-specific scientific tests.
+- Remove `Command` and `LegacyAlgorithmRepository`; all algorithm execution uses typed profiles and the runner.
+- Rename fitted prediction request fields to `fitted_algorithm` and bump those request schemas to 2.
+  External CLI argument names stay unchanged. Old request envelopes require explicit migration.
+- Require complete recorded fitted-input configuration instead of filling missing historical fields.
+- Expose `StepSpec.from_request_type` as the typed specification factory.
+- Separate configuration, every concrete request type, artifacts and execution in the UML guide;
+  include the per-test catalogue in the installed package.
+
 ### 0.4.0a4
 
 - Rename the repository/distribution from `meds-algorithm-core` to `meds-algorithm`, the Python package

meds_algorithm-0.4.0a4/PKG-INFO → meds_algorithm-0.4.0a5/README.md

@@ -1,31 +1,7 @@
-Metadata-Version: 2.5
-Name: meds-algorithm
-Version: 0.4.0a4
-Summary: Shared MEDS algorithm contracts and conformance boundaries.
-Project-URL: Repository, https://github.com/McDermottHealthAI/meds-algorithm
-Project-URL: Documentation, https://github.com/McDermottHealthAI/meds-algorithm/blob/main/ARCHITECTURE.md
-License-Expression: MIT
-License-File: LICENSE
-Requires-Python: >=3.11
-Requires-Dist: pyyaml>=6
-Provides-Extra: conformance
-Requires-Dist: meds-evaluation==0.0.3; extra == 'conformance'
-Requires-Dist: polars>=1; extra == 'conformance'
-Requires-Dist: pyarrow>=15; extra == 'conformance'
-Requires-Dist: pytest>=8; extra == 'conformance'
-Provides-Extra: data
-Requires-Dist: polars>=1; extra == 'data'
-Provides-Extra: test
-Requires-Dist: meds-evaluation==0.0.3; extra == 'test'
-Requires-Dist: polars>=1; extra == 'test'
-Requires-Dist: pyarrow>=15; extra == 'test'
-Requires-Dist: pytest>=8; extra == 'test'
-Description-Content-Type: text/markdown
-
 # meds-algorithm
 
 [![Python 3.11+](https://img.shields.io/badge/Python-3.11%2B-blue?logo=python&logoColor=white)](https://www.python.org/downloads/)
-[![PyPI: unreleased](https://img.shields.io/badge/PyPI-unreleased-lightgrey)](https://github.com/McDermottHealthAI/meds-algorithm/blob/main/RELEASING.md)
+[![PyPI](https://img.shields.io/pypi/v/meds-algorithm)](https://pypi.org/project/meds-algorithm/)
 [![Tests and code quality](https://github.com/McDermottHealthAI/meds-algorithm/actions/workflows/ci.yml/badge.svg)](https://github.com/McDermottHealthAI/meds-algorithm/actions/workflows/ci.yml)
 [![Documentation](https://img.shields.io/badge/docs-architecture-blue)](https://github.com/McDermottHealthAI/meds-algorithm/blob/main/ARCHITECTURE.md)
 [![Contributors](https://img.shields.io/github/contributors/McDermottHealthAI/meds-algorithm)](https://github.com/McDermottHealthAI/meds-algorithm/graphs/contributors)
@@ -53,7 +29,8 @@ src/meds_algorithm/
 ├── configuration.py            # AlgorithmConfig, NNConfig and execution options
 ├── serialization.py            # strict, versioned config/request JSON serialization
 ├── runner.py                   # validate, execute, measure, publish; CLI adapter
-├── contracts/commands.py       # derived compatibility views and legacy dispatch
+├── orchestration/              # optional Hydra planning, local subprocesses and Submitit jobs
+├── contracts/commands.py       # derived step specifications and validation
 ├── artifacts/
 │   ├── references.py           # lazy typed artifact references and payload metadata
 │   ├── manifest.py             # measured artifacts, envelope reading and digests
@@ -74,13 +51,13 @@ src/meds_algorithm/
 
 ## Installation and dependencies
 
-Install a reviewed revision with
-`pip install 'meds-algorithm @ git+https://github.com/McDermottHealthAI/meds-algorithm.git@<full-commit-sha>'`.
-The template currently records the exact SHA. For package-index release checks and publishing setup,
+Install from PyPI with `pip install 'meds-algorithm[data]'`. Pin a released version in algorithm
+repositories for reproducible environments. For package-index release checks and publishing setup,
 see the [release guide](https://github.com/McDermottHealthAI/meds-algorithm/blob/main/RELEASING.md).
 
 - Base package: PyYAML; no dataframe engine, test runner, GPU or algorithm framework is imported by base APIs.
 - `data` extra: Polars for index/target reads and prediction validation.
+- `orchestration` extra: Hydra configuration and Submitit; see the [prototype runner guide](src/meds_algorithm/ORCHESTRATION.md).
 - `conformance` extra: pytest, Polars, PyArrow and the pinned MEDS evaluation schema implementation.
 - `test` extra: dependencies for developing and testing this package.
 
@@ -115,8 +92,7 @@ layout into that interface; these upstream names are not part of this package's
 
 ## Publication, provenance and measurement
 
-Pass the algorithm checkout explicitly to `StepRunner(repo=algorithm_root)` or, for legacy implementations,
-`measured_artifact(..., repo=algorithm_root)`. The package never
+Pass the algorithm checkout explicitly to `StepRunner(repo=algorithm_root)`. The package never
 infers the algorithm from its own installation path or the working directory. Without a supplied checkout,
 commit and dirty state are unknown (`null`); wheel deployments must retain algorithm build provenance
 separately rather than inventing a checkout revision.
@@ -136,6 +112,8 @@ values as `null`. GPU instrumentation remains the algorithm/framework's responsi
 
 ## Validation
 
+See [the test catalogue](src/meds_algorithm/TESTING.md) for what each test checks, why it exists, and the limits of the suite.
+
 ```bash
 uv sync --extra test --group dev
 uv run ruff check .
@@ -156,6 +134,21 @@ training. Keep each algorithm's data-access and cluster approval rules in its ow
 
 ## Changes
 
+### 0.4.0a5 (2026-11-03)
+
+- Add an optional profile-runner prototype: shared Hydra schema, resolved dry-run plans, local
+  subprocess execution and dependent Submitit SLURM jobs. Existing per-step APIs remain unchanged.
+
+- Ship an opt-in `AlgorithmConformanceTests` acceptance suite and typed `AlgorithmCase` adapter;
+  generated repositories inherit the checks and retain algorithm-specific scientific tests.
+- Remove `Command` and `LegacyAlgorithmRepository`; all algorithm execution uses typed profiles and the runner.
+- Rename fitted prediction request fields to `fitted_algorithm` and bump those request schemas to 2.
+  External CLI argument names stay unchanged. Old request envelopes require explicit migration.
+- Require complete recorded fitted-input configuration instead of filling missing historical fields.
+- Expose `StepSpec.from_request_type` as the typed specification factory.
+- Separate configuration, every concrete request type, artifacts and execution in the UML guide;
+  include the per-test catalogue in the installed package.
+
 ### 0.4.0a4
 
 - Rename the repository/distribution from `meds-algorithm-core` to `meds-algorithm`, the Python package