millwright 0.1.0__tar.gz → 0.2.0__tar.gz

millwright-0.2.0/.github/workflows/release-crate.yml

@@ -0,0 +1,50 @@
+name: release-crate
+
+# Publish the Rust crate to crates.io when a version tag is pushed
+# (`git tag v0.1.1 && git push --tags`), using crates.io Trusted Publishing
+# (OIDC) — no stored token. A manual run (workflow_dispatch) does a `--dry-run`.
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    name: publish to crates.io
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write # required for crates.io Trusted Publishing (OIDC)
+    steps:
+      - uses: actions/checkout@v5
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+
+      - name: check tag matches Cargo.toml version
+        if: startsWith(github.ref, 'refs/tags/')
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          version="$(cargo metadata --no-deps --format-version 1 | jq -r '.packages[0].version')"
+          echo "tag=$tag  Cargo.toml=$version"
+          if [ "$tag" != "$version" ]; then
+            echo "::error::tag v$tag does not match Cargo.toml version $version"
+            exit 1
+          fi
+
+      - name: authenticate to crates.io (OIDC)
+        if: startsWith(github.ref, 'refs/tags/')
+        id: auth
+        uses: rust-lang/crates-io-auth-action@v1
+
+      - name: publish
+        if: startsWith(github.ref, 'refs/tags/')
+        env:
+          CARGO_REGISTRY_TOKEN: ${{ steps.auth.outputs.token }}
+        run: cargo publish --locked
+
+      - name: dry-run (manual runs only)
+        if: ${{ !startsWith(github.ref, 'refs/tags/') }}
+        run: cargo publish --locked --dry-run

{millwright-0.1.0 → millwright-0.2.0}/.github/workflows/release-python.yml

@@ -99,6 +99,8 @@ jobs:
     needs: [linux, windows, macos, sdist]
     # Only publish on a version tag; a manual run just builds the wheels above.
     if: startsWith(github.ref, 'refs/tags/')
+    permissions:
+      id-token: write # PyPI Trusted Publishing (OIDC) — no stored token
     steps:
       - uses: actions/download-artifact@v4
         with:
@@ -106,9 +108,7 @@ jobs:
           merge-multiple: true
           path: dist
       - name: publish
-        uses: PyO3/maturin-action@v1
-        env:
-          MATURIN_PYPI_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
+        uses: pypa/gh-action-pypi-publish@release/v1
         with:
-          command: upload
-          args: --non-interactive --skip-existing dist/*
+          packages-dir: dist
+          skip-existing: true

millwright-0.2.0/CHANGELOG.md

@@ -0,0 +1,118 @@
+# Changelog
+
+All notable changes to Millwright are recorded here. The format follows
+[Keep a Changelog](https://keepachangelog.com/), and the project aims at
+[Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-08-23
+
+### Added
+- **rayon parallelism.** Cross-validation folds and search candidates now
+  evaluate in parallel: `cross_val_score` is fold-parallel, `Bagging` fits its
+  base estimators in parallel, and `AutoML::parallel()` adds candidate-level
+  parallelism. The core contract traits gained `Send + Sync` bounds (every
+  concrete model already satisfied them). Results stay seed-reproducible.
+- **`Boosting`** — SAMME adaptive boosting over any weak learner (an
+  `alpha`-weighted vote of models each reweighted toward the last round's
+  mistakes), joining `Voting`/`Bagging`/`Stacking`.
+- **Three more models over the smartcore backend:** `Knn` (k-nearest-neighbours),
+  `Svc` (support vector classifier, linear or RBF, one-vs-one for multiclass),
+  and `NaiveBayes` (Gaussian). All implement the same `Estimator`/`Predictor`
+  contract, so they drop into pipelines, ensembles, and search unchanged — and
+  they are exposed to Python too (`mw.Knn`, `mw.Svc` / `mw.Svc.rbf()`,
+  `mw.NaiveBayes`, plus `pipe.knn()` / `pipe.svc()` / `pipe.naive_bayes()`).
+- **Python: a scikit-learn-shaped object API.** `mw.Frame` with `from_pandas` /
+  `from_numpy` / `from_rows` ingest; composable transformer/estimator objects
+  (`StandardScaler`, `MinMaxScaler`, `SimpleImputer`, `OneHotEncoder`,
+  `RandomForest`, `LinearRegression`) added via `pipe.step(name, obj)` /
+  `pipe.estimator(name, obj)`; `fit`/`predict`/`evaluate` accept a `Frame`.
+- **Python: `pipeline.explain(...)`** returns SHAP feature importance
+  (`Explainer.kernel()` configurable), and **`pipeline.export_onnx(path)`**
+  writes the fitted pipeline to a single ONNX file. The `python` wheel now
+  bundles the `model-selection`, `explain`, and `onnx` engines.
+- **Python: `GridSearch` / `KFold` / `StratifiedKFold`** over a pipeline, with
+  a `SearchResult` (`best_score`, `best_params()`, `predict()`).
+- **`InferenceModel` is now an `Estimator` + `Predictor`**, so a pre-trained
+  ONNX model (from scikit-learn, PyTorch, …) can be dropped into a `Pipeline`
+  as a frozen estimator behind Millwright's preprocessing — in Rust and, via
+  `mw.OnnxModel(path)`, from Python.
+- **Python: `mw.Table` + `mw.Profile`** — dtype-aware CSV/Parquet ingest and
+  automated EDA (`Profile.of(table_or_frame).to_html(path)`). The wheel now
+  bundles the `eda` (polars) engine, so it is larger than the pure-model build.
+- **`Table::from_frame`** (Rust): build a numeric `Table` from a `Frame`, so the
+  numeric world can round-trip back into the typed one (e.g. to profile it).
+- **Richer EDA in `Profile`** — excess `kurtosis` and z-score outlier counts per
+  numeric column; a **Spearman** rank-correlation matrix beside the Pearson one;
+  a **co-missing** map (columns whose null patterns correlate); high-cardinality
+  categoricals now suggest `TargetEncoder`; and `suggest_pipeline` adds a
+  train-time **SMOTE** balancer on class imbalance (with `preprocessing`).
+- **AutoML is seeded by EDA.** With the `eda` engine on, the search fixes its
+  preprocessing to `Profile::suggest_pipeline()` and varies only the model,
+  pruning the space (it falls back to a scaler sweep without `eda`).
+
+### Fixed
+- **Cross-validated F1 no longer returns `NaN`.** A fold whose predictions
+  contain no true positives left smartcore's F1 evaluating `0/0`; a single NaN
+  fold poisoned the CV mean and a search's `best_score`. An undefined F1 is now
+  0.0 (scikit-learn's `zero_division=0` convention), so `GridSearch(...).scoring(F1)`
+  yields finite, comparable scores.
+
+## [0.1.1]
+
+### Added
+
+- **`LogisticRegression`** — a native, core binary classifier with genuine
+  `predict_proba`: the framework's first real `ProbaPredictor`.
+- **`calibration` feature** — `PlattScaling`, `IsotonicRegression`,
+  `reliability_curve`, and `CalibratedClassifier`, which wraps any
+  `ProbaPredictor` and returns calibrated probabilities.
+- **`anomaly` feature** — `Mahalanobis` and `KnnScore`, unified behind an
+  `OutlierDetector` trait.
+- **`eda` feature** — a polars-backed, dtype-aware `Table` (CSV/Parquet ingest
+  that lowers to the numeric `Frame`) and a typed `Profile` with an HTML report,
+  actionable alerts, and `suggest_pipeline()`.
+- **Transformers** — `Winsorize`, `PowerTransform` (Yeo-Johnson),
+  `ColumnTransformer`, and the supervised `TargetEncoder`.
+- **Convenience** — `Frame::from_csv` (dependency-free numeric loader),
+  `Table::head`.
+- **Python** — `min_max_scaler`, `simple_imputer`, `one_hot`,
+  `linear_regression`, and `evaluate()`.
+- **Examples** — `explore` (ingest → profile → pipeline) and `trust`
+  (calibration → reliability → anomaly detection).
+- **Benchmarks** — `benches/throughput.rs` (criterion): the boundary conversion
+  and core fit/predict, backing the "Rust speed" claim.
+- **One-hot ingest** — `Table::to_frame_with` / `into_dataset_with` and a
+  `CategoryEncoding` enum: lower nominal categories to 0/1 indicator columns
+  instead of ordinal codes.
+- **Schema-aware preprocessing** — `Frame` carries a per-column `Dtype`; `Table`
+  marks categoricals as it lowers; scalers / `Winsorize` / `PowerTransform` pass
+  categorical columns through untouched, and `OneHotEncoder` encodes by dtype
+  rather than a value heuristic when the schema is known.
+- **Real-data validation** — an end-to-end integration test on Quinlan's
+  PlayTennis (`tests/real_data.rs`): CSV → profile → suggested pipeline → fit.
+
+### Changed
+
+- Exact-version pins on every engine crate; `Cargo.lock` committed; a
+  feature-matrix CI (fmt, clippy `-D warnings`, docs, matrix, OS, examples,
+  benches, publish dry-run, wheel).
+- `selection.rs` split into `selection/{scoring,cv,search}`.
+- MSRV is **1.95** (dep-dictated — `sysinfo` via tract, and polars); enforced by
+  cargo via `rust-version` rather than a dedicated CI job (which would break on
+  every transitive bump). The default install needs 1.85.
+- De-staled the crate and module docs (no more "Phase 0 · the spine").
+
+### Fixed
+
+- Golden tests and the crate doctest build under every feature subset (they were
+  unconditionally referencing backend-gated types).
+- Float sorts use `f64::total_cmp`, closing a NaN-driven panic class.
+
+## [0.1.0]
+
+- Phases 0–8: the `Frame`/trait spine and smartcore backend, preprocessing and
+  model selection, a second backend (linfa) and HPO, evaluation/diagnostics/
+  explainability, ONNX export and inference, serving + drift monitoring + a model
+  registry, time-series and out-of-core estimators, AutoML, and 1.0 hardening.

millwright-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,55 @@
+# Contributing to Millwright
+
+Thanks for your interest! Millwright assembles proven Rust crates into one
+composable ML lifecycle. Bug reports, small fixes, and focused features are all
+welcome.
+
+## Getting set up
+
+```bash
+git clone https://github.com/mi7plus/millwright
+cd millwright
+cargo test              # default features
+```
+
+Rust **1.95+** is required (the floor is dictated by transitive engine deps).
+
+## Before you open a PR
+
+The CI is a feature matrix, so run the same checks locally:
+
+```bash
+cargo fmt --all --check
+cargo clippy --features full --all-targets -- -D warnings
+cargo test --features full
+cargo test --no-default-features            # the bare-core build must pass too
+cargo doc --no-deps --features full         # with RUSTDOCFLAGS="-D warnings"
+```
+
+- **Every capability is a cargo feature.** New functionality behind a young
+  single-author crate goes behind its own feature; the core stays lean. See the
+  feature list in `Cargo.toml`.
+- **Engines are pinned to exact versions** (`=x.y.z`) and `Cargo.lock` is
+  committed — bump them deliberately, one line, one commit.
+- **Add tests.** Prefer a `#[test]` next to the code; lock numeric behaviour in
+  `tests/golden.rs` when it matters. Feature-gate tests that need a backend.
+- **Run the examples** you touch: `cargo run --features full --example <name>`.
+
+## Try it out
+
+- Examples: [`examples/`](examples) — one runnable program per feature group.
+- Benchmarks: `cargo bench --features smartcore-backend`.
+- Docs/tutorial: <https://millwright-rs.dev/docs/>.
+
+## Releasing
+
+Maintainers: bump `Cargo.toml` + `pyproject.toml`, roll `CHANGELOG.md`, and tag
+`vX.Y.Z` — the workflows publish to crates.io and PyPI via OIDC. The helper
+`scripts/release.sh X.Y.Z` does the mechanical steps. See
+[`RELEASING.md`](RELEASING.md).
+
+## Scope & conduct
+
+Millwright is a thin facade over proven engines — it orchestrates, it doesn't
+reimplement numerics. Please keep PRs focused, and be kind and constructive in
+issues and reviews.

{millwright-0.1.0 → millwright-0.2.0}/Cargo.lock

@@ -1935,7 +1935,7 @@ dependencies = [
 
 [[package]]
 name = "millwright"
-version = "0.1.0"
+version = "0.2.0"
 dependencies = [
  "axum",
  "chronos-ts",
@@ -1957,6 +1957,7 @@ dependencies = [
  "plotters-statistical",
  "polars",
  "pyo3",
+ "rayon",
  "regression-diagnostics",
  "serde",
  "serde_json",

{millwright-0.1.0 → millwright-0.2.0}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "millwright"
-version = "0.1.0"
+version = "0.2.0"
 edition = "2021"
 rust-version = "1.95"
 description = "A unified ML framework for Rust — proven Rust crates, assembled into one machine."
@@ -56,6 +56,7 @@ polars = { version = "=0.55.2", default-features = false, features = ["csv", "pa
 # --- general infrastructure: caret ranges, reproduced via Cargo.lock ---
 pyo3 = { version = "0.24", features = ["extension-module", "abi3-py39"], optional = true }
 ndarray = { version = "0.16", optional = true }
+rayon = { version = "1", optional = true }
 plotters = { version = "0.3.7", default-features = false, features = ["svg_backend", "all_series"], optional = true }
 tract-onnx = { version = "0.23", optional = true }
 axum = { version = "0.8", optional = true }
@@ -90,11 +91,13 @@ smartcore-backend = ["dep:smartcore"]
 preprocessing = ["dep:imbalance-rs", "dep:ndarray"]
 
 # Cross-validation splitters, scoring, and grid/random search over a pipeline.
-model-selection = ["dep:model-selection-rs", "dep:ndarray"]
+# CV folds and search candidates are evaluated in parallel via rayon.
+model-selection = ["dep:model-selection-rs", "dep:ndarray", "dep:rayon"]
 
 # Voting / bagging / stacking meta-estimators, composed over the four traits.
-# Leak-free stacking uses the model-selection CV engine when it is enabled.
-ensemble = []
+# Leak-free stacking uses the model-selection CV engine when it is enabled;
+# bagging fits its base estimators in parallel via rayon.
+ensemble = ["dep:rayon"]
 
 # Ingest & EDA — the front of the lifecycle. A polars-backed, dtype-aware
 # `Table` (CSV/Parquet in, real string/categorical/datetime/null columns) that
@@ -151,7 +154,7 @@ onnx = [
 # Deliberately NOT part of `full`: pyo3's `extension-module` defers libpython
 # symbols, so a plain `cargo test`/`clippy` cannot link a test binary with it.
 # Build & test this feature through maturin instead (see pyproject.toml).
-python = ["dep:pyo3", "smartcore-backend"]
+python = ["dep:pyo3", "smartcore-backend", "model-selection", "explain", "onnx", "eda"]
 
 # Phase 5 · OPERATIONS — past where scikit-learn stops.
 # A versioned model registry: content-addressed ONNX artifact + metadata +

millwright-0.2.0/GUIDE.md

@@ -0,0 +1,41 @@
+# The Millwright Guide
+
+*A unified ML framework for Rust — ten crates, one lifecycle.*
+
+The full hands-on tutorial now lives as a browsable, multi-page site:
+
+### → **[millwright-rs.dev/docs/](https://millwright-rs.dev/docs/)**  (source in [`docs/`](docs/index.html))
+
+It walks the whole lifecycle, one topic per page: **Data & EDA** · **Pipelines &
+Models** · **Insight** (evaluate, explain, calibrate, detect) · **Deploy**
+(ONNX, serving, registry, AutoML) · **Python**.
+
+## Quickstart
+
+```toml
+[dependencies]
+millwright = "0.1"          # or features = ["full"] for the whole lifecycle
+```
+
+```rust
+use millwright::prelude::*;
+
+// features as rows + a target -> a Dataset
+let train = Dataset::new(x, y)?;
+
+// standardize, then a random forest — one composable object
+let mut pipe = Pipeline::new()
+    .step("scale", StandardScaler::new())
+    .estimator("rf", RandomForest::new());
+
+pipe.fit(&train)?;
+let preds = pipe.predict(&test)?;
+```
+
+## Where to go
+
+- **Tutorial:** <https://millwright-rs.dev/docs/> — the full, hands-on walk-through.
+- **API reference:** [docs.rs/millwright](https://docs.rs/millwright).
+- **Design brief (the *why*):** <https://millwright-rs.dev/>.
+- **Examples:** [`examples/`](examples) — a runnable program for each feature group.
+- **Python:** [`pip install millwright`](https://pypi.org/project/millwright/).

{millwright-0.1.0 → millwright-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: millwright
-Version: 0.1.0
+Version: 0.2.0
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: 3
 Classifier: Intended Audience :: Science/Research
@@ -16,10 +16,19 @@ Project-URL: Repository, https://github.com/mi7plus/millwright
 
 # millwright
 
+[![crates.io](https://img.shields.io/crates/v/millwright.svg)](https://crates.io/crates/millwright)
+[![docs.rs](https://img.shields.io/docsrs/millwright)](https://docs.rs/millwright)
+[![PyPI](https://img.shields.io/pypi/v/millwright.svg)](https://pypi.org/project/millwright/)
+[![CI](https://github.com/mi7plus/millwright/actions/workflows/ci.yml/badge.svg)](https://github.com/mi7plus/millwright/actions/workflows/ci.yml)
+[![downloads](https://img.shields.io/crates/d/millwright.svg)](https://crates.io/crates/millwright)
+[![license](https://img.shields.io/crates/l/millwright.svg)](LICENSE)
+
 A unified ML framework for Rust — *ten crates, one lifecycle.*
 
-- **Tutorial:** [`GUIDE.md`](GUIDE.md) — the hands-on walk through the whole
-  lifecycle (also as a page: [`guide.html`](guide.html)).
+- **Tutorial:** the hands-on docs site at <https://millwright-rs.dev/docs/>
+  (source in [`docs/`](docs/index.html); a short [`GUIDE.md`](GUIDE.md) has the
+  quickstart).
+- **Contributing:** see [`CONTRIBUTING.md`](CONTRIBUTING.md).
 - **Design brief:** the *why*, at **<https://millwright-rs.dev/>**.
 
 > *"Ten crates"* is the ecosystem this project assembles —
@@ -108,7 +117,12 @@ A unified ML framework for Rust — *ten crates, one lifecycle.*
   (a full round-trip); tree-ensemble ONNX-ML artifacts run in external runtimes
   like onnxruntime.
 - **Python bindings** (`src/python.rs`, via [`pyo3`], feature `python`): a
-  `Pipeline` class over the same Rust core, built with maturin into an abi3 wheel.
+  `Pipeline` class over the same Rust core, shipped on [PyPI](https://pypi.org/project/millwright/)
+  as an abi3 wheel.
+
+```bash
+pip install millwright
+```
 
 ```python
 import millwright as mw
@@ -119,11 +133,7 @@ pipe.fit(rows, labels)          # list[list[float]], list[float]
 preds = pipe.predict(rows)      # runs the Rust engine
 ```
 
-Build the Python module (from a virtualenv):
-
-```bash
-maturin develop --features python
-```
+To build from source (contributors), from a virtualenv: `maturin develop --features python`.
 
 [`regression-diagnostics`]: https://crates.io/crates/regression-diagnostics
 [`shap-rs`]: https://crates.io/crates/shap-rs

{millwright-0.1.0 → millwright-0.2.0}/README.md

@@ -1,9 +1,18 @@
 # millwright
 
+[![crates.io](https://img.shields.io/crates/v/millwright.svg)](https://crates.io/crates/millwright)
+[![docs.rs](https://img.shields.io/docsrs/millwright)](https://docs.rs/millwright)
+[![PyPI](https://img.shields.io/pypi/v/millwright.svg)](https://pypi.org/project/millwright/)
+[![CI](https://github.com/mi7plus/millwright/actions/workflows/ci.yml/badge.svg)](https://github.com/mi7plus/millwright/actions/workflows/ci.yml)
+[![downloads](https://img.shields.io/crates/d/millwright.svg)](https://crates.io/crates/millwright)
+[![license](https://img.shields.io/crates/l/millwright.svg)](LICENSE)
+
 A unified ML framework for Rust — *ten crates, one lifecycle.*
 
-- **Tutorial:** [`GUIDE.md`](GUIDE.md) — the hands-on walk through the whole
-  lifecycle (also as a page: [`guide.html`](guide.html)).
+- **Tutorial:** the hands-on docs site at <https://millwright-rs.dev/docs/>
+  (source in [`docs/`](docs/index.html); a short [`GUIDE.md`](GUIDE.md) has the
+  quickstart).
+- **Contributing:** see [`CONTRIBUTING.md`](CONTRIBUTING.md).
 - **Design brief:** the *why*, at **<https://millwright-rs.dev/>**.
 
 > *"Ten crates"* is the ecosystem this project assembles —
@@ -92,7 +101,12 @@ A unified ML framework for Rust — *ten crates, one lifecycle.*
   (a full round-trip); tree-ensemble ONNX-ML artifacts run in external runtimes
   like onnxruntime.
 - **Python bindings** (`src/python.rs`, via [`pyo3`], feature `python`): a
-  `Pipeline` class over the same Rust core, built with maturin into an abi3 wheel.
+  `Pipeline` class over the same Rust core, shipped on [PyPI](https://pypi.org/project/millwright/)
+  as an abi3 wheel.
+
+```bash
+pip install millwright
+```
 
 ```python
 import millwright as mw
@@ -103,11 +117,7 @@ pipe.fit(rows, labels)          # list[list[float]], list[float]
 preds = pipe.predict(rows)      # runs the Rust engine
 ```
 
-Build the Python module (from a virtualenv):
-
-```bash
-maturin develop --features python
-```
+To build from source (contributors), from a virtualenv: `maturin develop --features python`.
 
 [`regression-diagnostics`]: https://crates.io/crates/regression-diagnostics
 [`shap-rs`]: https://crates.io/crates/shap-rs

millwright-0.2.0/RELEASING.md

@@ -0,0 +1,94 @@
+# Releasing
+
+Millwright ships as one Rust crate (crates.io) and one Python wheel (PyPI), from
+the same source.
+
+## The easy way
+
+With `main` green and `CHANGELOG.md`'s `[Unreleased]` section filled in, run:
+
+```bash
+bash scripts/release.sh 0.1.2
+```
+
+It bumps both manifests, rolls the changelog, syncs `Cargo.lock`, verifies the
+package, commits, tags `v0.1.2`, and (after a prompt) pushes — which triggers the
+publish workflows below. The rest of this file is the manual equivalent.
+
+## Preflight (manual)
+
+1. `main` is green in CI and `CHANGELOG.md`'s `[Unreleased]` section is current.
+2. Bump the version in **both** `Cargo.toml` and `pyproject.toml`, move the
+   changelog's `[Unreleased]` entries under the new version, and commit.
+3. Prove the packaged crate builds exactly as crates.io will build it:
+
+   ```bash
+   cargo publish --dry-run --locked
+   ```
+
+## Rust crate → crates.io
+
+Automated by the **`release-crate.yml`** workflow, which publishes on a `v*` tag
+via **Trusted Publishing (OIDC)** — no token is stored anywhere. One-time setup,
+on crates.io (crate → Settings → Trusted Publishing → add GitHub):
+
+| field               | value              |
+| ------------------- | ------------------ |
+| Repository owner    | `mi7plus`          |
+| Repository name     | `millwright`       |
+| Workflow filename   | `release-crate.yml`|
+| Environment         | *(leave blank)*    |
+
+Then a tag (below) publishes; a manual run (Actions → release-crate → Run
+workflow) does a `--dry-run`. The workflow also fails fast if the tag doesn't
+match `Cargo.toml`'s version. To publish by hand instead: `cargo login <token>`
+then `cargo publish --locked`.
+
+docs.rs builds the documentation automatically with the `full` feature set (see
+`[package.metadata.docs.rs]` in `Cargo.toml`); the `python` feature is excluded
+there because it needs a Python interpreter.
+
+## Python wheel → PyPI
+
+The recommended path is the **`release-python.yml`** workflow, which builds
+Linux (x86_64 + aarch64), macOS (x86_64 + aarch64), and Windows wheels plus an
+sdist, and publishes them together via **Trusted Publishing (OIDC)** — no stored
+token. One-time setup, on PyPI:
+
+- **Existing project:** PyPI → Your projects → `millwright` → Manage →
+  Publishing → Add a new publisher (GitHub Actions).
+- **Before the first publish:** account → Publishing → add a *pending* publisher.
+
+| field               | value               |
+| ------------------- | ------------------- |
+| Owner               | `mi7plus`           |
+| Repository name     | `millwright`        |
+| Workflow name       | `release-python.yml`|
+| Environment         | *(leave blank)*     |
+
+*(A pending publisher also needs the PyPI Project Name, `millwright`.)*
+
+Then every release is just a tag:
+
+```bash
+git tag vX.Y.Z && git push --tags
+```
+
+The workflow builds all platforms and publishes on the tag. A manual run
+(Actions → release-python → Run workflow) builds the wheels *without* publishing,
+for a dry run.
+
+To publish a single platform's wheel by hand instead (only installable on that
+OS), from a Developer PowerShell/Prompt with a Python toolchain:
+
+```bash
+maturin publish            # needs MATURIN_PYPI_TOKEN set
+```
+
+## Notes
+
+- The crate pins its engines to exact versions and commits `Cargo.lock`, so a
+  publish is fully reproducible.
+- MSRV is declared in `Cargo.toml` (`rust-version`) and enforced by cargo for
+  consumers; it is dictated by transitive engine deps, so expect it to rise over
+  time.