inductive-mlxrl 0.2.3__tar.gz → 0.3.0__tar.gz

inductive_mlxrl-0.3.0/.github/scripts/audit_dependencies.py

@@ -0,0 +1,52 @@
+"""Audit every registry version in uv.lock, including other-platform dependencies."""
+
+from __future__ import annotations
+
+import subprocess
+import tempfile
+import tomllib
+from pathlib import Path
+
+
+def main() -> None:
+    lock = tomllib.loads(Path("uv.lock").read_text())
+    groups: list[dict[str, str]] = []
+    for package in lock["package"]:
+        if package["source"] == {"editable": "."}:
+            continue
+        if package["source"].get("registry") != "https://pypi.org/simple":
+            raise ValueError(f"Unrecognized dependency source for {package['name']}.")
+        hashes = {wheel["hash"] for wheel in package.get("wheels", [])}
+        if "sdist" in package:
+            hashes.add(package["sdist"]["hash"])
+        if not hashes:
+            raise ValueError(f"Missing locked hashes for {package['name']}.")
+        requirement = f"{package['name']}=={package['version']} " + " ".join(
+            f"--hash={digest}" for digest in sorted(hashes)
+        )
+        # pip-audit rejects duplicate names even when versions target other Pythons.
+        for group in groups:
+            if package["name"] not in group:
+                group[package["name"]] = requirement
+                break
+        else:
+            groups.append({package["name"]: requirement})
+    with tempfile.TemporaryDirectory(prefix="mlxrl-dependency-audit-") as directory:
+        for index, group in enumerate(groups):
+            requirements = Path(directory) / f"requirements-{index}.txt"
+            requirements.write_text("\n".join(group.values()) + "\n")
+            subprocess.run(
+                [
+                    "pip-audit",
+                    "--strict",
+                    "--disable-pip",
+                    "--require-hashes",
+                    "-r",
+                    str(requirements),
+                ],
+                check=True,
+            )
+
+
+if __name__ == "__main__":
+    main()

inductive_mlxrl-0.3.0/.github/scripts/verify_release.py

@@ -0,0 +1,78 @@
+"""Require versioned tags to identify a main commit with successful push CI."""
+
+from __future__ import annotations
+
+import ast
+import json
+import os
+import re
+import subprocess
+import tomllib
+import urllib.parse
+import urllib.request
+from pathlib import Path
+
+
+def verify_release(ref: str, sha: str, version: str, repository: str, token: str) -> None:
+    if not ref.startswith("refs/tags/"):
+        return
+    if not re.fullmatch(r"refs/tags/v[0-9]+\.[0-9]+\.[0-9]+", ref):
+        raise ValueError("Release tags must use vX.Y.Z.")
+    if ref != f"refs/tags/v{version}":
+        raise ValueError("Release tag must match the package version.")
+    if not re.fullmatch(r"[0-9a-f]{40}", sha):
+        raise ValueError("Release commit must be a full SHA.")
+    tagged = subprocess.check_output(["git", "rev-parse", f"{ref}^{{commit}}"], text=True).strip()
+    if tagged != sha:
+        raise ValueError("Release tag and workflow commit differ.")
+    if subprocess.run(["git", "merge-base", "--is-ancestor", sha, "origin/main"]).returncode:
+        raise ValueError("Release commit must already be on origin/main.")
+    query = urllib.parse.urlencode(
+        {"head_sha": sha, "branch": "main", "event": "push", "status": "success"}
+    )
+    request = urllib.request.Request(
+        f"https://api.github.com/repos/{repository}/actions/workflows/ci.yml/runs?{query}",
+        headers={
+            "Authorization": f"Bearer {token}",
+            "Accept": "application/vnd.github+json",
+            "X-GitHub-Api-Version": "2022-11-28",
+        },
+    )
+    with urllib.request.urlopen(request, timeout=30) as response:
+        runs = json.load(response)["workflow_runs"]
+    if not any(
+        run["head_sha"] == sha
+        and run["head_branch"] == "main"
+        and run["event"] == "push"
+        and run["status"] == "completed"
+        and run["conclusion"] == "success"
+        and run["path"] == ".github/workflows/ci.yml"
+        for run in runs
+    ):
+        raise ValueError("Release commit needs successful push CI on main.")
+
+
+def main() -> None:
+    version = tomllib.loads(Path("pyproject.toml").read_text())["project"]["version"]
+    module = ast.parse(Path("mlxrl/__init__.py").read_text())
+    package_version = next(
+        ast.literal_eval(node.value)
+        for node in module.body
+        if isinstance(node, ast.Assign)
+        and any(
+            isinstance(target, ast.Name) and target.id == "__version__" for target in node.targets
+        )
+    )
+    if package_version != version:
+        raise ValueError("Package and distribution versions must match.")
+    verify_release(
+        os.environ["GITHUB_REF"],
+        os.environ["GITHUB_SHA"],
+        version,
+        os.environ["GITHUB_REPOSITORY"],
+        os.environ.get("GH_TOKEN", ""),
+    )
+
+
+if __name__ == "__main__":
+    main()

{inductive_mlxrl-0.2.3 → inductive_mlxrl-0.3.0}/CHANGELOG.md

@@ -5,6 +5,42 @@ All notable changes to this project are documented here.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project uses semantic versioning once releases are cut.
 
+## [0.3.0] - 2026-10-30
+
+Score centering is experimental and disabled by default. Existing configurations
+continue to use GRPO. Enable it explicitly with `[algorithm] name = "score-centering"`.
+The local benchmarks do not establish a reliable quality or long-run stability gain.
+
+### Added
+
+- Experimental, opt-in single-turn score centering with actual post-filter,
+  post-temperature sampler probabilities, detached top-k/tail correction,
+  fp32 trainer probabilities, and micro-batch support.
+- Correctness gates for exact gradients, drift cancellation, sampling laws,
+  seeded capture parity across rollout engines, and padded optimizer updates.
+- A paired multi-seed 4-bit QLoRA benchmark with raw training diagnostics.
+
+### Changed
+
+- Update locked filelock to 4.2.1 and Ruff to 0.17.1, and pin setup-uv 10.3.2.
+
+## [0.2.4] - 2026-10-22
+
+### Security
+
+- Require MLX-LM 0.32.0 or later with its MLX 0.32.2 minimum, and disable custom
+  model and tokenizer Python execution in library, example, and benchmark loaders. The older minimum
+  allowed the unsafe `model_file` behavior addressed by upstream's
+  [CVE-2026-5843 fix](https://github.com/ml-explore/mlx-lm/pull/1385).
+- Parse answer and action tags in linear time to prevent malformed model
+  output from stalling reward evaluation and multi-turn rollouts.
+- Reject CLI output paths whose symlinks resolve outside the working directory.
+- Pin release actions to verified commits, freeze build and validation tools,
+  audit all locked dependencies in CI, and require release tags to match a
+  package version on main with successful push CI.
+- Add security reporting guidance, ownership of release controls, and weekly
+  dependency and action updates.
+
 ## [0.2.3] - 2026-10-21
 
 ### Changed

{inductive_mlxrl-0.2.3 → inductive_mlxrl-0.3.0}/CONTRIBUTING.md

@@ -77,6 +77,10 @@ with `datasets>=5.0.1,<6` to avoid CVE-2026-66007. This only affects the externa
 benchmark tools; the published package depends on MLX and MLX-LM. Remove the
 override when mlx-tune accepts a patched datasets release.
 
+Certifi and Pillow use a one-day package-age cutoff so their October 2026
+security patches can be installed promptly. Other dependencies retain the
+configured default cutoff.
+
 ## Release Cycle
 
 Releases are tag-driven and publish to PyPI through Trusted Publishing. Do not
@@ -90,21 +94,34 @@ One-time PyPI setup:
 - set environment name to `pypi`;
 - require manual approval on the GitHub `pypi` environment before publishing.
 
+Restrict the environment to tags matching `v*`, disable administrator bypass
+for environment approval, and protect release-tag creation, updates, and
+deletion so only repository administrators can perform them. Require the
+`Linux CPU-safe checks` status on main and retain pull-request review.
+
+The publisher runs the official PyPA container by digest. When updating it,
+resolve the upstream release's commit-tagged image from
+`ghcr.io/pypa/gh-action-pypi-publish`, verify its content digest and source
+metadata, and update the digest and source-commit comment together. Other
+actions use commit pins maintained by Dependabot.
+
 For each release:
 
-1. Update the version in `pyproject.toml`.
+1. Update the version in `pyproject.toml` and `mlxrl/__init__.py`, then run `uv lock`.
 2. Add the release notes to `CHANGELOG.md`.
 3. Run the local gates:
 
 ```bash
-UV_CACHE_DIR=.uv-cache uv run pytest
-UV_CACHE_DIR=.uv-cache uv run ruff check .
-UV_CACHE_DIR=.uv-cache uv run pyright
-UV_CACHE_DIR=.uv-cache uv build
-UV_CACHE_DIR=.uv-cache uv run --no-project --python 3.11 --with twine twine check dist/*
+UV_CACHE_DIR=.uv-cache uv sync --frozen --all-groups
+UV_CACHE_DIR=.uv-cache uv run --no-sync pytest
+UV_CACHE_DIR=.uv-cache uv run --no-sync ruff check .
+UV_CACHE_DIR=.uv-cache uv run --no-sync pyright
+UV_CACHE_DIR=.uv-cache uv run --no-sync python .github/scripts/audit_dependencies.py
+UV_CACHE_DIR=.uv-cache uv build --no-build-isolation --python .venv/bin/python
+UV_CACHE_DIR=.uv-cache uv run --no-sync twine check dist/*
 ```
 
-4. Commit and merge the release prep.
+4. Commit and merge the release prep, then wait for main's push CI to pass.
 5. Tag the release from `main`:
 
 ```bash
@@ -112,12 +129,13 @@ git tag -a vX.Y.Z -m "Release vX.Y.Z"
 git push origin vX.Y.Z
 ```
 
-The `Release` workflow builds the source distribution and wheel, checks package
-metadata with Twine, stores the artifacts, publishes them to PyPI from the
-`pypi` environment, and creates a GitHub Release with the built distributions
-attached. Running the workflow manually builds and checks artifacts without
-publishing because the publish and GitHub Release jobs only run for `v*.*.*`
-tags.
+The `Release` workflow first checks that the tag matches the package version,
+identifies a commit already on main, and has successful main push CI. It builds
+with frozen validation and build tools, checks metadata with Twine, stores the
+artifacts, and publishes signed distributions from the protected `pypi`
+environment after maintainer approval. The GitHub Release receives the same
+files. Manual runs on branches only build and check artifacts; manual runs on
+version tags must satisfy all publication controls.
 
 The PyPI distribution name is `inductive-mlxrl`; the Python import package and
 CLI command remain `mlxrl`.

{inductive_mlxrl-0.2.3 → inductive_mlxrl-0.3.0}/DESIGN.md

@@ -37,6 +37,13 @@ than widening the single-turn `Algorithm` contract. GiGPO is the first
 implementation: the rollout engine records env-provided state ids, while the
 algorithm owns anchor-state grouping and credit assignment.
 
+The experimental single-turn `SamplerAwareAlgorithm` sibling extends the loss
+input with a recorded sampler head and corresponding full-forward trainer
+logprobs. The engine dispatches through that protocol when a prepared batch has
+sampler records; it still imports no algorithm implementations. The first user
+is score centering, a token-mean REINFORCE objective with centered rewards.
+Existing algorithms continue through the original protocol and probability path.
+
 ## Agentic Environment Seam
 
 Agentic rollout is built around `EnvFactory(task, seed, group_index) ->
@@ -86,6 +93,17 @@ diagnostic data, not training data.
 
 ## Memory As A First-Class Constraint
 
+Experimental score centering captures the actual categorical sampling law after
+filtering and temperature, rather than treating raw model logprobs as sampler
+probabilities. Records contain the selected-token probability and a top-k head;
+the head is not renormalized. Persistent capture storage scales with completion
+tokens times k, rather than vocabulary size. All gradient-bearing candidate
+logprobs come from the trainer's full-forward path with fp32 normalization.
+The detached tail correction follows equations 8--10 of arXiv:2609.20807, using
+an exact zero sampler tail when its head exhausts all mass and a 1e-6 floor on
+the trainer tail for numerical stability. This path is opt-in, single-turn only,
+and requires separate measured memory and stability gates.
+
 Apple Silicon's unified memory is the deployment target, not an afterthought.
 The code supports per-layer MLX-LM gradient checkpointing because DeltaNet and
 linear-attention models otherwise keep O(sequence length) recurrent state live

{inductive_mlxrl-0.2.3 → inductive_mlxrl-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: inductive-mlxrl
-Version: 0.2.3
+Version: 0.3.0
 Summary: Small single-process RL post-training for LLMs on Apple Silicon with MLX.
 Project-URL: Homepage, https://github.com/inductiveML/mlxrl
 Project-URL: Repository, https://github.com/inductiveML/mlxrl
@@ -19,8 +19,8 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Requires-Python: >=3.11
-Requires-Dist: mlx-lm>=0.31.3; python_version < '3.15' and platform_system == 'Darwin' and platform_machine == 'arm64'
-Requires-Dist: mlx>=0.31.2; python_version < '3.15' and platform_system == 'Darwin' and platform_machine == 'arm64'
+Requires-Dist: mlx-lm>=0.32.0; python_version < '3.15' and platform_system == 'Darwin' and platform_machine == 'arm64'
+Requires-Dist: mlx>=0.32.2; python_version < '3.15' and platform_system == 'Darwin' and platform_machine == 'arm64'
 Description-Content-Type: text/markdown
 
 # mlxrl
@@ -43,6 +43,9 @@ fields may change before a 1.0 release.
 
 ## Quickstart
 
+Requires Apple Silicon, Python 3.11–3.14, MLX 0.32.2+, and MLX-LM 0.32.0+.
+See [SECURITY.md](SECURITY.md) for model trust boundaries and private reporting.
+
 ```bash
 git clone https://github.com/inductiveML/mlxrl.git
 cd mlxrl
@@ -352,6 +355,55 @@ import concrete algorithm implementations.
 | GSPO | sequence-level, length-normalized importance ratio and clipping |
 | RLOO | leave-one-out group baseline, no critic, no std-normalized advantage |
 | GiGPO | multi-turn episode advantage plus anchor-state step advantage |
+| Score centering (experimental) | centered rewards, token-mean REINFORCE with sampler-score correction |
+
+### Experimental score centering
+
+Score centering is an explicit single-turn opt-in based on
+[Marek and Ryabinin, 2026](https://arxiv.org/abs/2609.20807). Existing algorithm
+defaults and old-policy recompute semantics stay unchanged.
+
+```bash
+UV_CACHE_DIR=.uv-cache uv run mlxrl train \
+  --config examples/qwen3_0_6b_score_centering.toml \
+  --available-memory-gb 48
+```
+
+The config selects the objective and the number of sampler candidates to retain:
+
+```toml
+[algorithm]
+name = "score-centering"
+score_centering_top_k = 128
+```
+
+This objective uses group-centered rewards without standard-deviation scaling.
+The sampler records probabilities **after top-p, min-p, top-k, and temperature**,
+including the selected token's probability even when it falls outside the
+recorded head. Greedy sampling is recorded as a point mass. Candidate
+probabilities retain their original mass; the trainer approximates the remaining
+tail as described in the paper. The correction coefficients are detached, and
+trainer logprobs are normalized in fp32. `kl_beta` remains the independent
+adapter-disabled reference-model penalty.
+
+For the import API, construct `ScoreCenteringAlgorithm(sampler_top_k=128)` from
+`mlxrl.algo` and use `SamplingConfig(record_sampler_top_k=128)` for generation.
+Pass the resulting completions and that algorithm to `batch_from_rollouts` and
+`optimizer_step`. Missing sampler records are rejected. `Completion.sampler_trace`
+contains the selected-token and candidate probabilities; config-driven runs also
+save `sampler_logprobs`, `sampler_topk_ids`, and `sampler_topk_logprobs` in the
+output NPZ. Ordinary `old_policy_logprobs` remain separate.
+
+Capture works with naive, prefix-cached, batched, and compiled single-turn
+rollouts and preserves seeded token draws. The objective supports token-weighted
+micro-batching. Multi-turn/ECHO training is outside this initial experiment.
+The memory preflight estimates have not been calibrated for this objective.
+Its benefit and overhead on a particular model must be measured; the paper's
+large-model results do not establish a benefit for MLX QLoRA.
+
+The reproducible paired benchmark is `benchmarks/run_score_centering.py`; its
+protocol and measured results are in
+[the 4-bit benchmark report](benchmarks/results/score_centering_4bit_2026-10-30.md).
 
 ## Memory Preflight
 

{inductive_mlxrl-0.2.3 → inductive_mlxrl-0.3.0}/README.md

@@ -18,6 +18,9 @@ fields may change before a 1.0 release.
 
 ## Quickstart
 
+Requires Apple Silicon, Python 3.11–3.14, MLX 0.32.2+, and MLX-LM 0.32.0+.
+See [SECURITY.md](SECURITY.md) for model trust boundaries and private reporting.
+
 ```bash
 git clone https://github.com/inductiveML/mlxrl.git
 cd mlxrl
@@ -327,6 +330,55 @@ import concrete algorithm implementations.
 | GSPO | sequence-level, length-normalized importance ratio and clipping |
 | RLOO | leave-one-out group baseline, no critic, no std-normalized advantage |
 | GiGPO | multi-turn episode advantage plus anchor-state step advantage |
+| Score centering (experimental) | centered rewards, token-mean REINFORCE with sampler-score correction |
+
+### Experimental score centering
+
+Score centering is an explicit single-turn opt-in based on
+[Marek and Ryabinin, 2026](https://arxiv.org/abs/2609.20807). Existing algorithm
+defaults and old-policy recompute semantics stay unchanged.
+
+```bash
+UV_CACHE_DIR=.uv-cache uv run mlxrl train \
+  --config examples/qwen3_0_6b_score_centering.toml \
+  --available-memory-gb 48
+```
+
+The config selects the objective and the number of sampler candidates to retain:
+
+```toml
+[algorithm]
+name = "score-centering"
+score_centering_top_k = 128
+```
+
+This objective uses group-centered rewards without standard-deviation scaling.
+The sampler records probabilities **after top-p, min-p, top-k, and temperature**,
+including the selected token's probability even when it falls outside the
+recorded head. Greedy sampling is recorded as a point mass. Candidate
+probabilities retain their original mass; the trainer approximates the remaining
+tail as described in the paper. The correction coefficients are detached, and
+trainer logprobs are normalized in fp32. `kl_beta` remains the independent
+adapter-disabled reference-model penalty.
+
+For the import API, construct `ScoreCenteringAlgorithm(sampler_top_k=128)` from
+`mlxrl.algo` and use `SamplingConfig(record_sampler_top_k=128)` for generation.
+Pass the resulting completions and that algorithm to `batch_from_rollouts` and
+`optimizer_step`. Missing sampler records are rejected. `Completion.sampler_trace`
+contains the selected-token and candidate probabilities; config-driven runs also
+save `sampler_logprobs`, `sampler_topk_ids`, and `sampler_topk_logprobs` in the
+output NPZ. Ordinary `old_policy_logprobs` remain separate.
+
+Capture works with naive, prefix-cached, batched, and compiled single-turn
+rollouts and preserves seeded token draws. The objective supports token-weighted
+micro-batching. Multi-turn/ECHO training is outside this initial experiment.
+The memory preflight estimates have not been calibrated for this objective.
+Its benefit and overhead on a particular model must be measured; the paper's
+large-model results do not establish a benefit for MLX QLoRA.
+
+The reproducible paired benchmark is `benchmarks/run_score_centering.py`; its
+protocol and measured results are in
+[the 4-bit benchmark report](benchmarks/results/score_centering_4bit_2026-10-30.md).
 
 ## Memory Preflight
 

inductive_mlxrl-0.3.0/SECURITY.md

@@ -0,0 +1,35 @@
+# Security policy
+
+Security fixes target the latest released version. Use inductive-mlxrl 0.2.4 or
+later and MLX-LM 0.32.0 or later. Earlier supported MLX-LM versions could execute
+Python from a model's `model_file` configuration without an explicit trust flag.
+See the [upstream fix](https://github.com/ml-explore/mlx-lm/pull/1385).
+
+Report vulnerabilities through the repository's
+[private vulnerability reporting form](https://github.com/inductiveML/mlxrl/security/advisories/new).
+Include the affected version, a minimal reproduction, and the expected impact.
+Keep credentials and private training data out of reports and public issues.
+
+## Trust boundaries
+
+Model completions and action text are untrusted data. Built-in tag parsers scan
+fixed delimiters without regex backtracking. Model loading explicitly disables
+custom remote Python code.
+
+Training configurations, custom Python reward functions, environment callbacks,
+benchmark command adapters, model repositories, and adapter files must come from
+sources you trust. The library runs in the caller's process and does not provide
+a sandbox for these extensions or for native tensor parsers. CLI output paths
+must resolve inside the working directory; this check does not isolate a
+process from another user who can concurrently change its files or symlinks.
+
+## Release controls
+
+Release tags must match the package version, identify a commit already on main,
+and have successful main push CI. CI audits every locked dependency version,
+including packages for other platforms and Python versions. Release actions
+use verified commit pins and build tools come from the frozen lockfile.
+
+GitHub's `pypi` environment restricts publication to protected release tags and
+requires a maintainer's approval. PyPI publication uses OIDC Trusted Publishing
+and signed attestations. Local Metal tests remain a release requirement.

{inductive_mlxrl-0.2.3 → inductive_mlxrl-0.3.0}/THIRD_PARTY_LICENSES.md

@@ -44,3 +44,12 @@ CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 - License: MIT per installed package metadata.
 - Used for: benchmark configuration inspection and external baseline adapter
   patterns only. No `mlx-lm-lora` implementation code is vendored in `mlxrl`.
+
+## Score centering research
+
+- Martin Marek and Max Ryabinin, *Score Centering Stabilizes Off-policy
+  Reinforcement Learning* (2026): https://arxiv.org/abs/2609.20807.
+- The experimental MLX objective implements the mathematics in equations 8--10
+  with independently written MLX code and explicit gradient-equivalence tests.
+  The paper is a research reference, not an installed dependency. This objective
+  is distinct from Tinker's StableReinforce service implementation.

{inductive_mlxrl-0.2.3 → inductive_mlxrl-0.3.0}/benchmarks/external_baseline_worker.py

@@ -317,7 +317,9 @@ def run_mlx_lm_lora(args: argparse.Namespace) -> BenchResult:
         prompt_token_lengths = [
             encoded_prompt_token_count(tokenizer, row["prompt"]) for row in rows
         ]
-        ref_loaded = load(args.model)
+        ref_loaded = load(
+            args.model, tokenizer_config={"trust_remote_code": False}, trust_remote_code=False
+        )
         ref_model = ref_loaded[0]
         ref_model.freeze()
         optimizer = optim.Adam(learning_rate=args.learning_rate)
@@ -453,6 +455,7 @@ def run_mlx_tune(args: argparse.Namespace) -> BenchResult:
         model_name=args.model,
         max_seq_length=args.max_context,
         load_in_4bit=True,
+        trust_remote_code=False,
     )
     prompt_token_lengths = [
         encoded_prompt_token_count(tokenizer, row["prompt"]) for row in rows