medmlx-core 0.1.2__tar.gz

medmlx_core-0.1.2/.gitignore

@@ -0,0 +1,26 @@
+__pycache__/
+*.py[cod]
+.venv/
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+
+# Checkpoints and converted weights are never committed.
+checkpoints/
+weights/
+*.safetensors
+*.npz
+!tests/fixtures/*.npz
+!tests/fixtures/*/*.npz
+*.pt
+*.pth
+*.ckpt
+
+# Imaging data is never committed.
+data/
+*.nii
+*.nii.gz
+*.dcm
+.DS_Store

medmlx_core-0.1.2/.hypothesis/.gitignore

@@ -0,0 +1,9 @@
+# This .gitignore file was automatically created by Hypothesis. Hypothesis gitignores
+# .hypothesis by default, because we generally recommend that .hypothesis not be checked
+# into version control.
+#
+# If you *would* like to check .hypothesis into version control, you should delete this
+# file. Hypothesis will not re-create this .gitignore unless .hypothesis is deleted (and
+# if it does, that's a bug - please report it!)
+
+*

medmlx_core-0.1.2/.hypothesis/constants/08abc73d38e2a158

@@ -0,0 +1,4 @@
+# file: /private/var/folders/_b/0j6pnq_16w7bgz89p1tx637m0000gn/T/medmlx-public-release-ht52soje/core/src/medmlx_core/checkpoints.py
+# hypothesis_version: 6.168.5
+
+['HostArray', '_maybe_array', 'cpu', 'detach', 'mapping_from_pairs', 'numpy']

medmlx_core-0.1.2/.hypothesis/constants/0d8ec412b22beadb

@@ -0,0 +1,4 @@
+# file: /private/var/folders/_b/0j6pnq_16w7bgz89p1tx637m0000gn/T/medmlx-public-release-ht52soje/core/src/medmlx_core/__init__.py
+# hypothesis_version: 6.168.5
+
+['0.1.2', 'AssetNotReadyError', 'Float32Operators', 'InvalidInputError', 'MLX_EXTRA', 'MedmlxError', 'MlxHostReport', 'ModelExecutionError', 'as_fp32', 'avg_pool3d_ncdhw', 'conv3d_ncdhw', 'conv3d_weight_to_mlx', 'deconv2x_ncdhw', 'dense_patch_slices', 'group_norm_ncdhw', 'import_mlx', 'linear', 'mapping_from_pairs', 'probe_mlx_runtime', 'require_mlx_device', 'require_mlx_runtime', 'require_ncdhw', 'silu', 'split_conv3d_ncdhw', 'to_ncdhw', 'to_ndhwc', 'tokens_from_ncdhw', 'tokens_to_ncdhw', 'upsample_add_ncdhw']

medmlx_core-0.1.2/.hypothesis/constants/34990f1212c247ce

@@ -0,0 +1,4 @@
+# file: /private/var/folders/_b/0j6pnq_16w7bgz89p1tx637m0000gn/T/medmlx-public-release-ht52soje/core/src/medmlx_core/runtime.py
+# hypothesis_version: 6.168.5
+
+['-n', '.', '/usr/sbin/sysctl', 'Darwin', 'MLX_EXTRA', 'MlxHostReport', '__version__', 'apple_chip', 'arm64', 'available', 'get_peak_memory', 'gpu', 'hint', 'hw.memsize', 'import_mlx', 'macos_version', 'memory_bytes', 'metal', 'mlx', 'mlx is not installed', 'mlx_version', 'platform_machine', 'platform_system', 'probe_mlx_runtime', 'python_version', 'reason', 'require_mlx_device', 'require_mlx_runtime', 'reset_peak_memory']

medmlx_core-0.1.2/.hypothesis/constants/396a64bc0176d3a9

@@ -0,0 +1,4 @@
+# file: /private/var/folders/_b/0j6pnq_16w7bgz89p1tx637m0000gn/T/medmlx-public-release-ht52soje/core/src/medmlx_core/layout.py
+# hypothesis_version: 6.168.5
+
+['attention input', 'maisi.layout.embed_w', 'maisi.layout.ncdhw', 'maisi.layout.vector']

medmlx_core-0.1.2/.hypothesis/constants/3bbd74727a5a8204

@@ -0,0 +1,4 @@
+# file: /private/var/folders/_b/0j6pnq_16w7bgz89p1tx637m0000gn/T/medmlx-public-release-ht52soje/core/src/medmlx_core/upsample.py
+# hypothesis_version: 6.168.5
+
+[255, 256, 'decoder input', 'decoder skip', 'math_mode', 'out', 'safe', 'skip', 'x']

medmlx_core-0.1.2/.hypothesis/constants/3e9c700c66f9d9c5

@@ -0,0 +1,4 @@
+# file: /private/var/folders/_b/0j6pnq_16w7bgz89p1tx637m0000gn/T/medmlx-public-release-ht52soje/core/src/medmlx_core/channel_last.py
+# hypothesis_version: 6.168.5
+
+[1e-05, 0.01]

medmlx_core-0.1.2/.hypothesis/constants/6116a31f7220fa84

@@ -0,0 +1,4 @@
+# file: /private/var/folders/_b/0j6pnq_16w7bgz89p1tx637m0000gn/T/medmlx-public-release-ht52soje/core/src/medmlx_core/errors.py
+# hypothesis_version: 6.168.5
+
+['AssetNotReadyError', 'InvalidInputError', 'MedmlxError', 'ModelExecutionError']

medmlx_core-0.1.2/.hypothesis/constants/6f29e0369cfb318e

@@ -0,0 +1,4 @@
+# file: /private/var/folders/_b/0j6pnq_16w7bgz89p1tx637m0000gn/T/medmlx-public-release-ht52soje/core/src/medmlx_core/ops.py
+# hypothesis_version: 6.168.5
+
+['avg pool input', 'conv3d input', 'group_norm input', 'linear', 'mlx.nn', 'skip concat left', 'skip concat right', 'spatial pad input', 'split_conv3d']

medmlx_core-0.1.2/.hypothesis/constants/86bf87a3fa3f2620

@@ -0,0 +1,4 @@
+# file: /private/var/folders/_b/0j6pnq_16w7bgz89p1tx637m0000gn/T/medmlx-public-release-ht52soje/core/src/medmlx_core/precision.py
+# hypothesis_version: 6.168.5
+
+[127, 128, 256, 512, 'B', 'BIAS', 'EPS', 'M', 'MA', 'MEAN', 'MO', 'S', 'V', 'VA', 'VAR', 'VO', 'W', 'X', 'Y', 'affine', 'coeff', 'conv', 'f', 'finish', 'join', 'merge', 'tile']

medmlx_core-0.1.2/.hypothesis/constants/8bf2c9a81c8a39f4

@@ -0,0 +1,4 @@
+# file: /private/var/folders/_b/0j6pnq_16w7bgz89p1tx637m0000gn/T/medmlx-public-release-ht52soje/core/src/medmlx_core/sliding_window.py
+# hypothesis_version: 6.168.5
+
+[0.001, 0.125, 0.25, 'circular', 'constant', 'cpu', 'dense_patch_slices', 'edge', 'gaussian', 'gpu', 'reflect', 'replicate', 'wrap']

medmlx_core-0.1.2/.hypothesis/constants/cbb5757b65496821

@@ -0,0 +1,4 @@
+# file: /private/var/folders/_b/0j6pnq_16w7bgz89p1tx637m0000gn/T/medmlx-public-release-ht52soje/core/src/medmlx_core/conversion.py
+# hypothesis_version: 6.168.5
+
+['conversion', 'cpu']

medmlx_core-0.1.2/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   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.

medmlx_core-0.1.2/Makefile

@@ -0,0 +1,5 @@
+.PHONY: typecheck
+
+typecheck:
+	uv run --locked --extra dev pyright --project . --warnings
+	bash -o pipefail -c 'rg --files --hidden --no-ignore --glob "*.py" --glob "*.pyi" --null scripts src tests | xargs -0 uv run --locked --extra dev ruff check --config pyproject.toml --select TID251,ANN401 --ignore-noqa --no-force-exclude --'

medmlx_core-0.1.2/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.5
+Name: medmlx-core
+Version: 0.1.2
+Summary: Shared MLX runtime for MedMLX model packages
+Author: Joseph Sandoval, Alfredo Sandoval Jr.
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: THIRD_PARTY_NOTICES.md
+License-File: licenses/MONAI_LICENSE
+Requires-Python: <3.14,>=3.12
+Requires-Dist: mlx<0.33,>=0.32.3; platform_system == 'Darwin' and platform_machine == 'arm64'
+Requires-Dist: numpy<3,>=2.0
+Provides-Extra: conversion
+Requires-Dist: torch<3,>=2.6; extra == 'conversion'
+Provides-Extra: dev
+Requires-Dist: hypothesis<7,>=6.140; extra == 'dev'
+Requires-Dist: monai==1.6.0; extra == 'dev'
+Requires-Dist: numpy<3,>=2.2; extra == 'dev'
+Requires-Dist: pyright[nodejs]==1.1.414; extra == 'dev'
+Requires-Dist: pytest<10,>=8.4; extra == 'dev'
+Requires-Dist: ruff<1,>=0.13; extra == 'dev'
+Requires-Dist: torch==2.14.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# medmlx-core
+
+Shared runtime and MLX primitives for standalone MedMLX medical imaging models.
+Runtime dependencies are NumPy and MLX. Importing `medmlx_core` does not import
+MLX; Torch is loaded only when the optional checkpoint converter is called.
+No model architectures, pretrained weights, image I/O, or model runners are included.
+
+## Install and platform policy
+
+```sh
+uv pip install "medmlx-core @ git+https://github.com/MedMLX/medmlx-core.git@v0.1.2"
+```
+
+Only macOS arm64 with MLX on Metal is supported. `import_mlx()` admits the host
+and selects the Metal GPU. Unsupported hosts are rejected before importing MLX;
+unavailable Metal is an error. There are no backend extras or backend fallback.
+The existing `require_mlx_device("mlx")` API checks explicit MLX readiness.
+Python is `>=3.12,<3.14`; MLX is `>=0.32.3,<0.33`. Runtime admission rejects
+older or unsupported MLX versions before inference.
+
+The `conversion` extra supplies Torch for `load_torch_checkpoint()`. Safe
+`weights_only=True` loading is the default. Explicit `weights_only=False` remains
+available for trusted legacy payloads. Missing Torch reports `extra="conversion"`
+and the corresponding install hint.
+
+## Public API and references
+
+Main helpers are re-exported from `medmlx_core`. Errors derive from the real
+`MedmlxError` base and retain their built-in catch types: `InvalidInputError`
+(`ValueError`), `MissingDependencyError` (`ImportError`), `ModelExecutionError`
+(`RuntimeError`), and `AssetNotReadyError` (`FileNotFoundError`).
+
+The canonical reference pins are in `tests/reference_spec.json`. MONAI is
+1.6.0, revision [`eccefc57550b111ed781d82249dfe77872a0e918`](https://github.com/Project-MONAI/MONAI/tree/eccefc57550b111ed781d82249dfe77872a0e918).
+PyTorch is 2.14.1, revision [`5c4886908584029761b579af026dcfb627c84070`](https://github.com/pytorch/pytorch/tree/5c4886908584029761b579af026dcfb627c84070).
+Development dependencies pin these package versions; generators reject a different
+version or source revision. Reference frameworks are absent from runtime imports.
+
+| Module | API / independent reference |
+| --- | --- |
+| `runtime.py` | Host readiness, Metal admission and peak-memory counters; direct platform/API contract tests |
+| `errors.py` | Exception identity, messages and metadata; direct public contract tests |
+| `checkpoints.py`, `conversion.py` | Duplicate-safe host mappings and optional Torch deserialization; original seeded arrays and Torch save/load round trips |
+| `layout.py` | NCDHW/NDHWC, convolution-weight and token permutations; plain NumPy float64 reference |
+| `ops.py` | SiLU, linear, conv3d, conv_transpose3d, GroupNorm, pooling, interpolation, padding and concatenation; PyTorch functional operations |
+| `ops.py` split convolutions | Actual MONAI `MaisiConvolution`, including its overlap, integer size-ratio checks and crop semantics |
+| `upsample.py` | Kernel=stride=2 transpose convolution and fused trilinear interpolation + skip addition; PyTorch functional operations |
+| `precision.py` | Metal FP32 convolution and GroupNorm versus PyTorch; custom epsilon decomposition and Welford moments versus NumPy float64 |
+| `sliding_window.py` | MONAI `inferers/utils.py` and `data/utils.py` |
+| `channel_last.py` | PyTorch layers, MONAI Swish and `UnetResBlock`; individual layers and complete seeded 2D/3D graphs |
+
+Inference helpers run on Metal. Model topology, checkpoint keys, label meanings and
+pre/postprocessing belong to each model package. Channel-last references use the
+core's MONAI 1.6.0 pin; they do not qualify consumer models pinned to another release.
+
+## Sliding-window inference
+
+```python
+from medmlx_core import sliding_window_inference
+
+logits = sliding_window_inference(
+    image,  # NumPy or MLX (N, C, *spatial), float32/float16
+    roi_size=(128, 128, 128),
+    sw_batch_size=1,
+    predictor=network,  # MLX array -> MLX array, same spatial resolution
+    overlap=0.25,
+    mode="constant",
+    padding_mode="replicate",
+)
+```
+
+The result is a host NumPy array with the input dtype and original spatial size;
+output channels follow the predictor. Public helpers include `dense_patch_slices`
+and `compute_importance_map`. Scalar/per-axis overlap and sigma, fallback ROI
+components, all four Torch padding modes, supplied ROI maps, window batching
+across images, predictor arguments, and `with_coord` are supported. Batch size
+is used as supplied. The existing `sw_device` parameter accepts None, `"gpu"`
+or an MLX GPU device; CPU prediction is rejected. `device` is None or `"cpu"`
+because NumPy accumulation stays on the host. `import_mlx()` admits Metal before
+the predictor is invoked.
+
+Window stride is `max(int(roi * (1-overlap)), 1)`, with the final window shifted
+onto the edge. Small inputs receive symmetric padding, with an extra voxel on
+the right for odd deficits. Gaussian maps use FP32 separable factors, center
+`(size-1)/2`, sigma `size*sigma_scale`, no peak normalization, and minimum 0.001.
+Predictions are weighted in predictor dtype before ordered input-dtype accumulation.
+
+Multiple/scaled outputs, positive `buffer_steps`, `process_fn`, progress bars,
+and MetaTensor metadata are unsupported and fail explicitly where applicable.
+No background threshold or class-ID mapping is applied by the shared stitcher.
+Recorded postprocessing references use MONAI `AsDiscrete(argmax=True)` only.
+
+## Reference fixtures and regeneration
+
+Seven small upstream-reference archives are included under
+`tests/fixtures/darwin-arm64/` (each below 80 KB). Inputs retain the original
+seeds: 7081 for helpers and 20261007 for channel-last/window graphs. Coverage
+includes input/layout preparation, every helper, padding/cropping, window logits,
+coordinates, importance maps, argmax labels, and complete synthetic layer graphs.
+Each archive has `schema_version=2`, upstream versions/revisions, seed, reference
+device, NumPy version, Torch build and recording platform. Generators use Torch
+CPU and NumPy, import neither MedMLX nor MLX, and are never imported by the
+numerical tests.
+The reference frameworks execute on the CPU of this Mac; production inference
+uses MLX on Metal. Tests load the one recording directory directly, without
+backend selection. To regenerate on another Apple Silicon Mac:
+
+```sh
+export UV_CACHE_DIR="$TMPDIR/uv-cache"
+uv venv "$TMPDIR/venv-$(basename "$PWD")" --python 3.12
+uv pip install --python "$TMPDIR/venv-$(basename "$PWD")/bin/python" -e ".[dev,conversion]"
+export PYTHONDONTWRITEBYTECODE=1
+PYTHON="$TMPDIR/venv-$(basename "$PWD")/bin/python"
+
+"$PYTHON" scripts/make_reference_fixtures.py
+"$PYTHON" scripts/make_channel_last_fixtures.py
+"$PYTHON" scripts/make_sliding_window_fixtures.py
+
+RUFF_CACHE_DIR="$TMPDIR/ruff-cache-medmlx-core" "$PYTHON" -m ruff check .
+"$PYTHON" -m pytest -q -o cache_dir="$TMPDIR/pytest-cache-medmlx-core"
+```
+
+Generators require macOS arm64. `--output-dir` permits regeneration in a temporary
+directory for review. Missing references fail with a regeneration hint.
+
+Numerical policy is versioned in `tests/numerical_contract.json`. Every comparison
+checks shape, FP32 dtype and finite values. Copies, permutations, nearest-neighbor
+replication and discrete outputs compare exactly. Arithmetic compares with
+operation-specific absolute and relative bounds, accounting for reduction order,
+FMA and exponential rounding. Each channel-last layer is checked on its upstream
+stage input; complete graphs have a separate cumulative budget. The triage and
+bound rationale are in `tests/NUMERICAL_PARITY.md`. The repeated 48-cubed decoder
+test uses seeded weights and requires no external checkpoint.
+
+Independent sliding-window tests retain exact comparison for representable
+constant-blending inputs, maximum absolute error 1e-6 for Gaussian logits and
+1e-7 for Gaussian maps because NumPy/Torch FP32 exponential kernels round differently.
+
+**Qualification:** The reviewer ran the previous suite on Metal and reported
+159 passes, 35 failures from cross-framework bitwise arithmetic assertions and
+two skips. Those assertions and environment-dependent tests have been replaced;
+the revised numerical gates still require reviewer Metal verification. Host
+checks and reference generation do not qualify MLX execution. Reference arrays
+retain the independently recorded upstream outputs and provenance.
+
+Fixtures are synthetic helper references. Clinical accuracy, released model
+weights and full-volume memory/performance are not qualified by these fixtures.
+
+## License
+
+Apache-2.0; see [LICENSE](LICENSE). The built wheel includes the upstream MONAI
+license and existing third-party notices alongside the runtime modules.

medmlx_core-0.1.2/README.md

@@ -0,0 +1,152 @@
+# medmlx-core
+
+Shared runtime and MLX primitives for standalone MedMLX medical imaging models.
+Runtime dependencies are NumPy and MLX. Importing `medmlx_core` does not import
+MLX; Torch is loaded only when the optional checkpoint converter is called.
+No model architectures, pretrained weights, image I/O, or model runners are included.
+
+## Install and platform policy
+
+```sh
+uv pip install "medmlx-core @ git+https://github.com/MedMLX/medmlx-core.git@v0.1.2"
+```
+
+Only macOS arm64 with MLX on Metal is supported. `import_mlx()` admits the host
+and selects the Metal GPU. Unsupported hosts are rejected before importing MLX;
+unavailable Metal is an error. There are no backend extras or backend fallback.
+The existing `require_mlx_device("mlx")` API checks explicit MLX readiness.
+Python is `>=3.12,<3.14`; MLX is `>=0.32.3,<0.33`. Runtime admission rejects
+older or unsupported MLX versions before inference.
+
+The `conversion` extra supplies Torch for `load_torch_checkpoint()`. Safe
+`weights_only=True` loading is the default. Explicit `weights_only=False` remains
+available for trusted legacy payloads. Missing Torch reports `extra="conversion"`
+and the corresponding install hint.
+
+## Public API and references
+
+Main helpers are re-exported from `medmlx_core`. Errors derive from the real
+`MedmlxError` base and retain their built-in catch types: `InvalidInputError`
+(`ValueError`), `MissingDependencyError` (`ImportError`), `ModelExecutionError`
+(`RuntimeError`), and `AssetNotReadyError` (`FileNotFoundError`).
+
+The canonical reference pins are in `tests/reference_spec.json`. MONAI is
+1.6.0, revision [`eccefc57550b111ed781d82249dfe77872a0e918`](https://github.com/Project-MONAI/MONAI/tree/eccefc57550b111ed781d82249dfe77872a0e918).
+PyTorch is 2.14.1, revision [`5c4886908584029761b579af026dcfb627c84070`](https://github.com/pytorch/pytorch/tree/5c4886908584029761b579af026dcfb627c84070).
+Development dependencies pin these package versions; generators reject a different
+version or source revision. Reference frameworks are absent from runtime imports.
+
+| Module | API / independent reference |
+| --- | --- |
+| `runtime.py` | Host readiness, Metal admission and peak-memory counters; direct platform/API contract tests |
+| `errors.py` | Exception identity, messages and metadata; direct public contract tests |
+| `checkpoints.py`, `conversion.py` | Duplicate-safe host mappings and optional Torch deserialization; original seeded arrays and Torch save/load round trips |
+| `layout.py` | NCDHW/NDHWC, convolution-weight and token permutations; plain NumPy float64 reference |
+| `ops.py` | SiLU, linear, conv3d, conv_transpose3d, GroupNorm, pooling, interpolation, padding and concatenation; PyTorch functional operations |
+| `ops.py` split convolutions | Actual MONAI `MaisiConvolution`, including its overlap, integer size-ratio checks and crop semantics |
+| `upsample.py` | Kernel=stride=2 transpose convolution and fused trilinear interpolation + skip addition; PyTorch functional operations |
+| `precision.py` | Metal FP32 convolution and GroupNorm versus PyTorch; custom epsilon decomposition and Welford moments versus NumPy float64 |
+| `sliding_window.py` | MONAI `inferers/utils.py` and `data/utils.py` |
+| `channel_last.py` | PyTorch layers, MONAI Swish and `UnetResBlock`; individual layers and complete seeded 2D/3D graphs |
+
+Inference helpers run on Metal. Model topology, checkpoint keys, label meanings and
+pre/postprocessing belong to each model package. Channel-last references use the
+core's MONAI 1.6.0 pin; they do not qualify consumer models pinned to another release.
+
+## Sliding-window inference
+
+```python
+from medmlx_core import sliding_window_inference
+
+logits = sliding_window_inference(
+    image,  # NumPy or MLX (N, C, *spatial), float32/float16
+    roi_size=(128, 128, 128),
+    sw_batch_size=1,
+    predictor=network,  # MLX array -> MLX array, same spatial resolution
+    overlap=0.25,
+    mode="constant",
+    padding_mode="replicate",
+)
+```
+
+The result is a host NumPy array with the input dtype and original spatial size;
+output channels follow the predictor. Public helpers include `dense_patch_slices`
+and `compute_importance_map`. Scalar/per-axis overlap and sigma, fallback ROI
+components, all four Torch padding modes, supplied ROI maps, window batching
+across images, predictor arguments, and `with_coord` are supported. Batch size
+is used as supplied. The existing `sw_device` parameter accepts None, `"gpu"`
+or an MLX GPU device; CPU prediction is rejected. `device` is None or `"cpu"`
+because NumPy accumulation stays on the host. `import_mlx()` admits Metal before
+the predictor is invoked.
+
+Window stride is `max(int(roi * (1-overlap)), 1)`, with the final window shifted
+onto the edge. Small inputs receive symmetric padding, with an extra voxel on
+the right for odd deficits. Gaussian maps use FP32 separable factors, center
+`(size-1)/2`, sigma `size*sigma_scale`, no peak normalization, and minimum 0.001.
+Predictions are weighted in predictor dtype before ordered input-dtype accumulation.
+
+Multiple/scaled outputs, positive `buffer_steps`, `process_fn`, progress bars,
+and MetaTensor metadata are unsupported and fail explicitly where applicable.
+No background threshold or class-ID mapping is applied by the shared stitcher.
+Recorded postprocessing references use MONAI `AsDiscrete(argmax=True)` only.
+
+## Reference fixtures and regeneration
+
+Seven small upstream-reference archives are included under
+`tests/fixtures/darwin-arm64/` (each below 80 KB). Inputs retain the original
+seeds: 7081 for helpers and 20261007 for channel-last/window graphs. Coverage
+includes input/layout preparation, every helper, padding/cropping, window logits,
+coordinates, importance maps, argmax labels, and complete synthetic layer graphs.
+Each archive has `schema_version=2`, upstream versions/revisions, seed, reference
+device, NumPy version, Torch build and recording platform. Generators use Torch
+CPU and NumPy, import neither MedMLX nor MLX, and are never imported by the
+numerical tests.
+The reference frameworks execute on the CPU of this Mac; production inference
+uses MLX on Metal. Tests load the one recording directory directly, without
+backend selection. To regenerate on another Apple Silicon Mac:
+
+```sh
+export UV_CACHE_DIR="$TMPDIR/uv-cache"
+uv venv "$TMPDIR/venv-$(basename "$PWD")" --python 3.12
+uv pip install --python "$TMPDIR/venv-$(basename "$PWD")/bin/python" -e ".[dev,conversion]"
+export PYTHONDONTWRITEBYTECODE=1
+PYTHON="$TMPDIR/venv-$(basename "$PWD")/bin/python"
+
+"$PYTHON" scripts/make_reference_fixtures.py
+"$PYTHON" scripts/make_channel_last_fixtures.py
+"$PYTHON" scripts/make_sliding_window_fixtures.py
+
+RUFF_CACHE_DIR="$TMPDIR/ruff-cache-medmlx-core" "$PYTHON" -m ruff check .
+"$PYTHON" -m pytest -q -o cache_dir="$TMPDIR/pytest-cache-medmlx-core"
+```
+
+Generators require macOS arm64. `--output-dir` permits regeneration in a temporary
+directory for review. Missing references fail with a regeneration hint.
+
+Numerical policy is versioned in `tests/numerical_contract.json`. Every comparison
+checks shape, FP32 dtype and finite values. Copies, permutations, nearest-neighbor
+replication and discrete outputs compare exactly. Arithmetic compares with
+operation-specific absolute and relative bounds, accounting for reduction order,
+FMA and exponential rounding. Each channel-last layer is checked on its upstream
+stage input; complete graphs have a separate cumulative budget. The triage and
+bound rationale are in `tests/NUMERICAL_PARITY.md`. The repeated 48-cubed decoder
+test uses seeded weights and requires no external checkpoint.
+
+Independent sliding-window tests retain exact comparison for representable
+constant-blending inputs, maximum absolute error 1e-6 for Gaussian logits and
+1e-7 for Gaussian maps because NumPy/Torch FP32 exponential kernels round differently.
+
+**Qualification:** The reviewer ran the previous suite on Metal and reported
+159 passes, 35 failures from cross-framework bitwise arithmetic assertions and
+two skips. Those assertions and environment-dependent tests have been replaced;
+the revised numerical gates still require reviewer Metal verification. Host
+checks and reference generation do not qualify MLX execution. Reference arrays
+retain the independently recorded upstream outputs and provenance.
+
+Fixtures are synthetic helper references. Clinical accuracy, released model
+weights and full-volume memory/performance are not qualified by these fixtures.
+
+## License
+
+Apache-2.0; see [LICENSE](LICENSE). The built wheel includes the upstream MONAI
+license and existing third-party notices alongside the runtime modules.