lme-python 0.2.1__tar.gz → 0.2.2__tar.gz

{lme_python-0.2.1 → lme_python-0.2.2}/.github/workflows/audit.yml

@@ -28,7 +28,7 @@ jobs:
           toolchain: stable
 
       - name: Install cargo-audit
-        uses: taiki-e/install-action@c44f6b046f1c29ae5918b1e0bfdbb2f1813836fd # v2
+        uses: taiki-e/install-action@7f4eb899022d8fe70b20c4f3de697aa85c309026 # v2
         with:
           tool: cargo-audit@0.22.1
 

{lme_python-0.2.1 → lme_python-0.2.2}/.github/workflows/cache-prime.yml

@@ -54,7 +54,7 @@ jobs:
         if: matrix.os == 'macos-latest'
         run: echo "OPENBLAS_TARGET=ARMV8" >> "$GITHUB_ENV"
       - name: Cache Rust dependencies
-        uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
+        uses: Swatinem/rust-cache@a45951ff880207c249adf57334cf2e9bd81d6e1e # v2
         with:
           shared-key: ci-v2-${{ runner.os }}-rust-test
           cache-workspace-crates: ${{ runner.os != 'Linux' }}
@@ -76,7 +76,7 @@ jobs:
       - name: Install OpenBLAS
         run: sudo apt-get update && sudo apt-get install -y libopenblas-dev
       - name: Cache production-load Rust dependencies
-        uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
+        uses: Swatinem/rust-cache@a45951ff880207c249adf57334cf2e9bd81d6e1e # v2
         with:
           shared-key: ci-v2-${{ runner.os }}-rust-release
           cache-workspace-crates: true
@@ -105,11 +105,17 @@ jobs:
         if: matrix.os == 'macos-latest'
         run: echo "OPENBLAS_TARGET=ARMV8" >> "$GITHUB_ENV"
       - name: Cache Python Rust dependencies
-        uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
+        uses: Swatinem/rust-cache@a45951ff880207c249adf57334cf2e9bd81d6e1e # v2
         with:
           shared-key: ci-${{ runner.os }}-python
           workspaces: python -> target
       - name: Compile Python binding dependencies
+        if: matrix.os != 'macos-latest'
         env:
           PYO3_PYTHON: python
         run: cargo build --release --manifest-path python/Cargo.toml
+      - name: Compile Python binding dependencies (macOS)
+        if: matrix.os == 'macos-latest'
+        uses: PyO3/maturin-action@e83996d129638aa358a18fbd1dfb82f0b0fb5d3b # v1
+        with:
+          args: --release --out python/dist --manifest-path python/Cargo.toml

{lme_python-0.2.1 → lme_python-0.2.2}/.github/workflows/ci.yml

@@ -34,6 +34,8 @@ jobs:
           python-version: "3.11"
       - name: Validate legal notices and provenance
         run: python3 scripts/ci/lme_ci.py legal
+      - name: Validate Markdown links
+        run: python3 scripts/ci/lme_ci.py docs-links
       - name: Validate completion score claims
         run: python3 scripts/ci/lme_ci.py completion-check
 
@@ -54,7 +56,7 @@ jobs:
       - name: Install OpenBLAS
         run: sudo apt-get update && sudo apt-get install -y libopenblas-dev
       - name: Cache Rust dependencies
-        uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
+        uses: Swatinem/rust-cache@a45951ff880207c249adf57334cf2e9bd81d6e1e # v2
         with:
           shared-key: ci-v2-${{ runner.os }}-rust-test
           save-if: ${{ github.event_name == 'pull_request' || github.ref == 'refs/heads/master' }}
@@ -111,7 +113,7 @@ jobs:
           toolchain: stable
 
       - name: Cache Rust dependencies
-        uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
+        uses: Swatinem/rust-cache@a45951ff880207c249adf57334cf2e9bd81d6e1e # v2
         with:
           shared-key: ci-v2-${{ runner.os }}-rust-test
           cache-workspace-crates: true
@@ -139,7 +141,7 @@ jobs:
         run: sudo apt-get update && sudo apt-get install -y libopenblas-dev
 
       - name: Restore Rust dependencies
-        uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
+        uses: Swatinem/rust-cache@a45951ff880207c249adf57334cf2e9bd81d6e1e # v2
         with:
           shared-key: ci-v2-${{ runner.os }}-rust-release
           cache-workspace-crates: true
@@ -167,7 +169,7 @@ jobs:
       - name: Install OpenBLAS
         run: sudo apt-get update && sudo apt-get install -y libopenblas-dev
       - name: Cache Python Rust dependencies
-        uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
+        uses: Swatinem/rust-cache@a45951ff880207c249adf57334cf2e9bd81d6e1e # v2
         with:
           shared-key: ci-${{ runner.os }}-python
           workspaces: python -> target
@@ -181,7 +183,7 @@ jobs:
 
       - name: Python bindings (canonical editable identity + isolated wheel)
         if: matrix.python-version == '3.11'
-        run: python scripts/ci/lme_ci.py python --python-version ${{ matrix.python-version }}
+        run: python scripts/ci/lme_ci.py python --python-version ${{ matrix.python-version }} --examples
 
       - name: Python bindings (isolated wheel compatibility)
         if: matrix.python-version != '3.11'
@@ -203,7 +205,7 @@ jobs:
         if: matrix.os == 'macos-latest'
         run: echo "OPENBLAS_TARGET=ARMV8" >> "$GITHUB_ENV"
       - name: Cache Python Rust dependencies
-        uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
+        uses: Swatinem/rust-cache@a45951ff880207c249adf57334cf2e9bd81d6e1e # v2
         with:
           shared-key: ci-${{ runner.os }}-python
           workspaces: python -> target
@@ -215,7 +217,7 @@ jobs:
           enable-cache: true
           cache-dependency-glob: "python/uv.lock"
       - name: Python bindings (isolated wheel OS compatibility)
-        run: python scripts/ci/lme_ci.py python --python-version 3.11 --wheel-only
+        run: python scripts/ci/lme_ci.py python --python-version 3.11 --wheel-only --examples
 
   publish-crate:
     name: Publish Rust crate after CI
@@ -236,7 +238,7 @@ jobs:
     secrets: inherit
 
   publish-python:
-    name: Publish Python artifacts after CI
+    name: Dispatch Python release after CI
     if: startsWith(github.ref, 'refs/tags/v')
     needs:
       - release-policy
@@ -247,8 +249,19 @@ jobs:
       - python-bindings-versions
       - python-bindings-os
     permissions:
-      contents: write
-      id-token: write
-    uses: ./.github/workflows/python-release.yml
-    with:
-      publish: true
+      actions: write
+      contents: read
+    runs-on: ubuntu-latest
+    steps:
+      - name: Dispatch verified Python release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_SHA: ${{ github.sha }}
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: |
+          gh workflow run python-release.yml \
+            --repo "${GITHUB_REPOSITORY}" \
+            --ref master \
+            -f release_tag="${RELEASE_TAG}" \
+            -f release_sha="${RELEASE_SHA}" \
+            -f publish=true

{lme_python-0.2.1 → lme_python-0.2.2}/.github/workflows/fuzz-smoke.yml

@@ -31,7 +31,7 @@ jobs:
       - name: Install cargo-fuzz
         run: cargo install cargo-fuzz@0.13.2 --locked
 
-      - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
+      - uses: Swatinem/rust-cache@a45951ff880207c249adf57334cf2e9bd81d6e1e # v2
         with:
           workspaces: fuzz
 

{lme_python-0.2.1 → lme_python-0.2.2}/.github/workflows/python-release.yml

@@ -1,28 +1,96 @@
 name: Build and Publish Python Wheels
 
-# CI calls this workflow after every release-tag validation job succeeds.
-# workflow_dispatch remains available for non-publishing artifact builds.
+# CI dispatches this top-level workflow after every release-tag validation job
+# succeeds. PyPI Trusted Publishing does not support publishing from a reusable
+# workflow with attestations, so this workflow must retain its own identity.
 on:
-  workflow_call:
+  workflow_dispatch:
     inputs:
+      release_tag:
+        description: Validated v* tag to build; blank builds the selected ref
+        required: false
+        type: string
+        default: ""
+      release_sha:
+        description: Exact validated commit for a publishing run
+        required: false
+        type: string
+        default: ""
       publish:
-        description: Publish the built artifacts for a validated release tag
+        description: Publish the verified release tag to PyPI
         required: false
         type: boolean
         default: false
-  workflow_dispatch:
 
 permissions:
   contents: read
 
+env:
+  RELEASE_REF: ${{ inputs.release_tag || github.ref }}
+
 jobs:
+  verify-release:
+    name: Verify release target
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          ref: ${{ env.RELEASE_REF }}
+
+      - name: Verify validated tag and package versions
+        if: inputs.publish
+        env:
+          RELEASE_SHA: ${{ inputs.release_sha }}
+          RELEASE_TAG: ${{ inputs.release_tag }}
+        run: |
+          set -euo pipefail
+
+          if [[ ! "${RELEASE_TAG}" =~ ^v[0-9]+\.[0-9]+\.[0-9]+([.-][0-9A-Za-z.-]+)?$ ]]; then
+            echo "Publishing requires an explicit semantic v* release tag." >&2
+            exit 1
+          fi
+          if [[ ! "${RELEASE_SHA}" =~ ^[0-9a-f]{40}$ ]]; then
+            echo "Publishing requires the exact 40-character validated commit SHA." >&2
+            exit 1
+          fi
+
+          actual_sha="$(git rev-list -n 1 "refs/tags/${RELEASE_TAG}")"
+          if [[ "${actual_sha}" != "${RELEASE_SHA}" ]]; then
+            echo "Tag ${RELEASE_TAG} resolves to ${actual_sha}, not validated SHA ${RELEASE_SHA}." >&2
+            exit 1
+          fi
+          if [[ "$(git rev-parse HEAD)" != "${RELEASE_SHA}" ]]; then
+            echo "Checked-out release does not match validated SHA ${RELEASE_SHA}." >&2
+            exit 1
+          fi
+
+          python - "${RELEASE_TAG#v}" <<'PY'
+          import pathlib
+          import sys
+          import tomllib
+
+          expected = sys.argv[1]
+          manifests = (pathlib.Path("Cargo.toml"), pathlib.Path("python/Cargo.toml"))
+          for manifest in manifests:
+              with manifest.open("rb") as stream:
+                  actual = tomllib.load(stream)["package"]["version"]
+              if actual != expected:
+                  raise SystemExit(
+                      f"{manifest}: package version {actual!r} does not match tag {expected!r}"
+                  )
+          PY
+
   linux:
+    needs: verify-release
     runs-on: ubuntu-latest
     strategy:
       matrix:
         target: [x86_64, aarch64]
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ env.RELEASE_REF }}
       - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: '3.10'
@@ -59,12 +127,15 @@ jobs:
           path: dist
 
   windows:
+    needs: verify-release
     runs-on: windows-latest
     strategy:
       matrix:
         target: [x64]
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ env.RELEASE_REF }}
       - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: '3.10'
@@ -89,12 +160,15 @@ jobs:
           path: dist
 
   macos:
+    needs: verify-release
     runs-on: macos-latest
     strategy:
       matrix:
         target: [x86_64, aarch64]
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ env.RELEASE_REF }}
       - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: '3.10'
@@ -124,9 +198,12 @@ jobs:
           path: dist
 
   sdist:
+    needs: verify-release
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ env.RELEASE_REF }}
       - uses: dtolnay/rust-toolchain@4cda84d5c5c54efe2404f9d843567869ab1699d4 # stable
         with:
           toolchain: stable
@@ -147,14 +224,16 @@ jobs:
     name: Publish to PyPI
     needs: [linux, windows, macos, sdist]
     runs-on: ubuntu-latest
-    # Only CI's validated release-tag call can enable publication.
-    if: "inputs.publish && startsWith(github.ref, 'refs/tags/v')"
+    # Publication requires the explicit opt-in and exact tag/SHA verification above.
+    if: inputs.publish
     environment: pypi
     permissions:
       id-token: write  # IMPORTANT: this permission is mandatory for trusted publishing
       contents: write  # needed to create GitHub Release
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ env.RELEASE_REF }}
 
       - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
@@ -174,9 +253,10 @@ jobs:
           done
 
       - name: Publish to PyPI
-        uses: pypa/gh-action-pypi-publish@ba38be9e461d3875417946c167d0b5f3d385a247 # release/v1
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1
 
       - name: Upload to GitHub Release
         uses: softprops/action-gh-release@3d0d9888cb7fd7b750713d6e236d1fcb99157228 # v3.0.2
         with:
           files: dist/*
+          tag_name: ${{ inputs.release_tag }}

{lme_python-0.2.1 → lme_python-0.2.2}/AGENTS.md

@@ -10,6 +10,7 @@ Use the smallest validation tier that proves the change is sound, then run the e
 | Python bindings | `task lint:python`, `task python` |
 | CI, manifests, release tooling | `task preflight`; use `task ci` before a release or broad refactor |
 | R / Julia comparison scripts | `task lint:comparisons`; use `task lint:comparisons:required` when the formatters are installed |
+| Documentation or portable examples | `task docs:check`; use `task consumer:smoke` when install or example behavior changes |
 | LMM throughput paths (`src/math.rs`, `src/optimizer.rs`) | Read [OPTIMIZATION.md](OPTIMIZATION.md) and run the applicable fair-harness cases |
 | Completion score files: `README.md`, `REPO_COMPLETION_BY_AREA.md`, `completion_manifest.json`, or `scripts/ci/check_completion_score.py` | `task completion:check` |
 
@@ -70,11 +71,11 @@ Use `--no-verify` only when explicitly necessary; report the bypass and the chec
 
 ## CI and release boundaries
 
-GitHub Actions validation runs automatically on pull requests and `v*` tags, and can be manually dispatched. Ordinary non-PR branch pushes do not receive the hosted validation matrix automatically. A lightweight cache-prime workflow runs when Rust dependency inputs change on `master` and weekly so new PRs can reuse trusted dependency artifacts. Pull requests run the full matrix except the four ignored heavy production-load cases. The tag CI calls the crates.io and PyPI workflows only after every validation job succeeds; the publishing workflows do not listen to tags independently.
+GitHub Actions validation runs automatically on pull requests and `v*` tags, and can be manually dispatched. Ordinary non-PR branch pushes do not receive the hosted validation matrix automatically. A lightweight cache-prime workflow runs when Rust dependency inputs change on `master` and weekly so new PRs can reuse trusted dependency artifacts. Pull requests run the full matrix except the four ignored heavy production-load cases. The tag CI calls the crates.io workflow and dispatches the top-level PyPI workflow only after every validation job succeeds; the publishing workflows do not listen to tags independently. The PyPI workflow must remain top-level because Trusted Publishing attestations do not support a reusable publishing workflow.
 
 External GitHub Actions are pinned to full commit SHAs, with the readable release line retained as a comment. Dependabot proposes grouped weekly pin updates; do not replace SHA pins with mutable tags. Dependency audits and libFuzzer smoke tests run weekly in addition to their release/manual entry points.
 
-- `task ci` mirrors the core hosted flow: Rust tests, Python bindings, lint, all-targets check, legal checks, doctests, docs, and the completion-score check.
+- `task ci` mirrors the core hosted flow: Rust tests, Python bindings, portable consumer examples, lint, all-targets check, legal checks, documentation/link verification, and the completion-score check.
 - Hosted-only coverage includes the multi-OS matrix, Python 3.10–3.13, production-load gates, and `pip-audit`.
 - After changing BLAS target tables or release workflows, run `task ci` locally or manually dispatch CI before tagging; macOS Apple Silicon BLAS is not exercised on Windows/Linux.
 - Benchmark workflow coverage requiring R or Julia belongs in the tag/manual workflow. `task benchmarks:preflight` runs the Rust smoke plus the R smoke when R/lme4 is available.
@@ -93,8 +94,19 @@ For repository-metadata token issues, set `REPO_ADMIN_TOKEN` locally and run `ta
 | `task ci` / `task ci:fast` | Core CI mirror / reuse the editable Python environment and skip the isolated-wheel pass |
 | `task audit` / `task legal` | Security audit / provenance and license checks |
 | `task completion:check` | Verify the manifest-derived completion score and published markers |
+| `task docs:check` / `task consumer:smoke` | Validate docs/links/API examples / run clean-install Rust and Python workflows |
 | `task benchmarks:fair-rust-julia` | Fair fit-only Rust vs MixedModels.jl timing when Julia packages are installed |
 | `task benchmarks:perf-breakdown` | Rust phase timings against Julia optimizer evaluation counts |
+| `task benchmarks:external-timings` | Fair-ish `nlmer`, post-fit inference, and Python FFI timings vs R when available |
+| `task explorations` | Standalone native-parser AST, θ-grid, and MCP exploration examples |
 | `task lint:comparisons` | Optional R/Julia comparison formatting check |
 
 Run `python scripts/ci/lme_ci.py --help` for the complete command list. See [CONTRIBUTING.md](CONTRIBUTING.md) for contributor workflow and [RELEASING.md](RELEASING.md) for release steps.
+
+## Cursor Cloud specific instructions
+
+This repo is a pure Rust library (`lme-rs`) plus a PyO3/maturin Python binding (`lme_python`); there are no servers or long-running services. "Running the app" means building the crate and running examples/tests. See the command reference above for the canonical `task` aliases.
+
+- Toolchain comes from `mise` (per [mise.toml](mise.toml): Rust stable, Python 3.11, `uv`, `task`, `lefthook`). The startup update script runs `mise install`. Interactive shells auto-activate mise via `~/.bashrc`. In a non-interactive shell where `mise`/`task`/`uv` aren't on `PATH`, run `eval "$($HOME/.local/bin/mise activate bash --shims)"` first (or invoke tools with `$HOME/.local/bin/mise exec -- <cmd>`).
+- On x86_64 the core crate links Intel MKL statically via `ndarray-linalg`, so no `gfortran`/system BLAS is needed; the first `cargo build`/`task test:fast` compiles MKL and takes a few minutes (subsequent builds are cached). Examples must be run with `--release` (e.g. `cargo run --release --example sleepstudy`) — a debug build is very slow.
+- Python bindings gotcha: `uv sync` / `task ci` / `task python` reinstall the venv and **uninstall** the maturin-built `lme_python` before rebuilding it. If you run a bare `uv sync` (or interrupt `task python` before its maturin step), `import lme_python` breaks; restore it with `cd python && uv run --no-sync maturin develop --release` (or re-run `task python`). Run Python examples from `python/` via `uv run --no-sync python examples/<name>.py`.

{lme_python-0.2.1 → lme_python-0.2.2}/BENCHMARKS.md

@@ -436,7 +436,7 @@ The repository also includes a dedicated workflow in [.github/workflows/benchmar
 
 ## Latest published results
 
-Release-attached Criterion and cross-language JSON artifacts are uploaded by [`.github/workflows/benchmarks.yml`](../.github/workflows/benchmarks.yml) on `v*` tags (and manual dispatch). Prefer the [latest GitHub Release](https://github.com/x4g4p3x/lme-rs/releases/latest) for downloadable CI artifacts, and [`CHANGELOG.md`](CHANGELOG.md) for which crate version each tag ships.
+Release-attached Criterion and cross-language JSON artifacts are uploaded by [`.github/workflows/benchmarks.yml`](.github/workflows/benchmarks.yml) on `v*` tags (and manual dispatch). Prefer the [latest GitHub Release](https://github.com/x4g4p3x/lme-rs/releases/latest) for downloadable CI artifacts, and [`CHANGELOG.md`](CHANGELOG.md) for which crate version each tag ships.
 
 **Engineering source of truth for fair Rust vs Julia fit timing** is the checked-in reference JSON under [`benchmarks/`](benchmarks/), especially the full strict-target [2026-07-22 tier-A artifact](benchmarks/fair-rust-julia-reference-2026-07-22-full-tier-a.json). Older tags (for example [v0.1.3](https://github.com/x4g4p3x/lme-rs/releases/tag/v0.1.3)) still carry historical CI tarballs useful for release-to-release comparison, but they are **not** the current performance baseline.
 

{lme_python-0.2.1 → lme_python-0.2.2}/BENCHMARK_COVERAGE.md

@@ -2,7 +2,7 @@
 
 This file maps **which parts of `lme-rs` have external performance references** (not just Rust-only Criterion benches). Use it to ground [REPO_COMPLETION_BY_AREA.md](REPO_COMPLETION_BY_AREA.md) axis (3) and [USABILITY.md](USABILITY.md) performance posture.
 
-**Last assessed:** 2026-07-22
+**Last assessed:** 2026-08-14
 
 ---
 
@@ -50,16 +50,19 @@ Hot-path target (batch / CV): **`fit_prepared` ≤ ~1× Julia `fit`** when `--wi
 | `cbpp_binomial_ml` | GLMM | Real binomial | MixedModels.jl GLMM | **0.749×** | N/A | Laplace; not R `nAGQ`-in-θ |
 | `grouseticks_poisson_ml` | GLMM | Real Poisson | MixedModels.jl GLMM | **0.033×** | N/A | Laplace |
 
-Cases not in tier A (no fair external fit timing yet):
+Cases not in tier A (no fair MixedModels.jl fit timing yet):
 
 | Area | Rust bench | Comparable | Status |
 |:-----|:-----------|:-----------|:-------|
-| `nlmer` / Orange | Golden parity only | `lme4::nlmer` | **No** fair harness |
+| `nlmer` / Orange | Golden parity + [`scripts/run_external_timings.py`](scripts/run_external_timings.py) | `lme4::nlmer` | **External R timing** (not Julia) |
 | GLMM AGQ (`n_agq > 1`) | Criterion | R semantics differ | **No** apples-to-apples |
-| Post-fit inference (KR, ANOVA, predict) | Criterion | `lmerTest` / MixedModels | **No** external timing |
-| Python `lme_python` FFI | None | N/A | **No** |
+| Post-fit inference (KR, ANOVA, predict) | Criterion + external harness | `lmerTest` when installed | **External R timing** for KR / Satterthwaite ANOVA |
+| LMM estimated marginal means / pairs | Criterion (`inference/emmeans_*`) | R `emmeans` correctness fixture | **Rust microbenchmark**; no cross-language speed claim |
+| Python `lme_python` FFI | External harness | Rust `lmer` | **External Python timing** |
 | `lm` / `lm_df` | Minimal | R `lm` | **No** (usually negligible) |
 
+The 2026-08-14 Windows Criterion run measured `inference/emmeans_reference_grid` at **42.5–43.1 µs** and `inference/emmeans_pairs_tukey` at **52.9–56.8 µs** on the pastes fixture. These are post-fit operations and do not warrant a specialized cache at the current scale.
+
 ---
 
 ## What each completion row may claim
@@ -101,6 +104,19 @@ using Pkg; Pkg.add("GLM")
 
 ---
 
+### External nlmer / inference / Python timings
+
+Julia is not required. Times Rust and R `nlmer`, Rust Kenward–Roger / Satterthwaite ANOVA (and `lmerTest` when installed), and `lme_python.lmer` FFI overhead:
+
+```powershell
+python scripts/run_external_timings.py --repeats 5 --output benchmarks/external-nlmm-inference-python-timings.json
+task benchmarks:external-timings
+```
+
+A dated reference JSON lives under [`benchmarks/`](benchmarks/). Use `--rust-only` for a smoke that skips R and Python.
+
+---
+
 ## Maintenance
 
 1. After optimization work on a workflow, add or refresh its tier-A case.

{lme_python-0.2.1 → lme_python-0.2.2}/CHANGELOG.md

@@ -7,6 +7,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.2] - 2026-08-14
+
+### Added
+
+- **Estimated marginal means (`emmeans`)** — [`LmeFit::emmeans`](src/emmeans.rs) builds equal-weight categorical reference grids for linear models/LMMs, holding numeric columns at their means; [`LmeFit::emmeans_pairs`](src/emmeans.rs) adds none / Bonferroni / Holm / Tukey–Kramer pairwise comparisons. Rust and Python APIs support asymptotic `z` or stored Satterthwaite / Kenward–Roger dfs. Pastes `cask` estimates, SEs, confidence limits, and Tukey pairs are locked directly to R `emmeans` in [`tests/data/pastes_emmeans.json`](tests/data/pastes_emmeans.json).
+- **Tukey / Dunnett multiple comparisons (`glht`)** — [`LmeFit::glht`](src/mcp.rs) implements `multcomp::mcp` pairwise (Tukey) and vs-control (Dunnett) Wald tests with Bonferroni, Holm, or Tukey–Kramer (`stats::ptukey`) adjustment. Default is asymptotic `z`; Satterthwaite / Kenward–Roger `t` is optional. Pastes `cask` fixture: [`tests/data/pastes_glht_tukey.json`](tests/data/pastes_glht_tukey.json).
+- **R formula edge-case fit matrix** — eight lme4 goldens covering independent `||` slopes, `I(Days^2)`, `sqrt(Days)`, raw/orthogonal `poly()`, `ns()`, cell-means `0 + cask`, and nested `batch/cask` ([`tests/data/r_edge_case_matrix.json`](tests/data/r_edge_case_matrix.json), [`tests/test_r_edge_case_matrix.rs`](tests/test_r_edge_case_matrix.rs)).
+- **External `nlmer` / inference / Python FFI timings** — [`scripts/run_external_timings.py`](scripts/run_external_timings.py) times Rust and R `nlmer`, Kenward–Roger / Satterthwaite ANOVA, and `lme_python.lmer` FFI overhead (Julia not required).
+- **Native-parser explorations** — standalone examples [`explore_formula_ast`](examples/explore_formula_ast.rs), [`explore_theta_grid`](examples/explore_theta_grid.rs), and [`explore_mcp_adjust`](examples/explore_mcp_adjust.rs), tested in [`tests/test_explorations.rs`](tests/test_explorations.rs) and run by `task explorations`.
+- **Profile-likelihood CIs for variance components** — [`confint_profile_vc`](src/profile_ci.rs) / [`confint_profile_all`](src/profile_ci.rs) match lme4 `confint.merMod(..., method = "profile")` on the `oldNames=TRUE` scale: `.sig01` is the RE SD (`θ·σ`) for a scalar random intercept and `.sigma` is the residual SD. [`BootLmerResult::confint_percentile_vc`](src/bootstrap.rs) summarizes the same parameters from bootstrap draws. Sleepstudy ML fixture: [`tests/data/sleepstudy_confint_profile_vc.json`](tests/data/sleepstudy_confint_profile_vc.json).
+- Formula materialization for two-way colon interactions (`a:b`), unary column transforms (`log`, `sqrt`, `exp`), `I()` arithmetic, and `offset(log(x))`-style transformed offsets. These terms are now built into the design matrix instead of being rejected at parse time.
+- Formula `poly()`, `ns()`, and `y ~ .` materialization. Orthogonal or raw `poly(x, degree)` and natural cubic `ns(x, df)` become design-matrix columns; training encodings are reused by `predict`. `.` expands to remaining DataFrame columns except the response and names already in the formula.
+- Multivariate **AGQ-in-θ** for GLMMs and `nlmer`: when `n_agq ≥ 2`, the outer θ search uses adaptive Gauss–Hermite quadrature for vector random effects (product rule per group) and for multiple RE terms when total `q` is small enough. Scalar `k = 1` still matches `lme4`; vector/joint AGQ-in-θ goes beyond lme4 (which stays Laplace for multivariate RE). Large crossed models remain Laplace-in-θ.
+- Python `lm(y, x)` for numeric OLS (same calling shape as Rust `lm(y, x)`). `lm(formula, data)` is unchanged; `lm_matrix` remains an alias.
+
+### Changed
+
+- [`FormulaModel::offset`](src/formula.rs) is now `Option<NumericExpr>` so transformed offsets can be represented. Plain column offsets still work; use [`FormulaModel::offset_column`](src/formula.rs) when you need the old string form.
+- Tag CI dispatches the top-level PyPI Trusted Publishing workflow only after every validation job succeeds; `task ci` now includes consumer-smoke and documentation/link gates.
+
+### Fixed
+
+- Non-numeric `offset()` columns (and other numeric formula terms) are rejected again when values cannot be parsed as floats. Formula materialization had dropped invalid entries instead of erroring, which let string offsets fit.
+- Gamma GLMM random-effect θ no longer collapses to the bound: PIRLS profiles residual φ (IRLS weights `1/φ`, unscaled `u'u` penalty) and scalar θ uses a log-grid plus golden-section search. `gamma_dyestuff_log_laplace` now locks Batch θ against lme4 VarCorr Std.Dev.
+
 ## [0.2.1] - 2026-08-10
 
 ### Changed

{lme_python-0.2.1 → lme_python-0.2.2}/CONTRIBUTING.md

@@ -60,6 +60,9 @@ task test:fast   # cargo test --lib only (quick unit tests)
 task test        # full Rust test suite
 task preflight   # pre-push hook: lint + check + cargo audit + repo-metadata dry-run
 task audit       # cargo audit + pip-audit (GHA security audit mirror)
+task docs:check  # local Markdown links + Rust examples/doctests + generated docs
+task consumer:smoke # Rust quick-start + clean-wheel Python examples
+task explorations # native-parser AST / θ-grid / MCP probes
 task rust        # full Rust slice (no Python)
 task             # full core CI mirror
 task ci:fast     # reuse python/.venv, skip isolated-wheel pytest
@@ -105,7 +108,7 @@ uv lock
 
 Use `uv run --no-sync pytest tests/` after the explicit `uv sync` so only [`python/tests/`](python/tests/) runs against the extension Maturin just installed; `pytest` alone also collects optional demos under `python/examples/`.
 
-[`task python`](Taskfile.yml) / [`scripts/ci/lme_ci.py python`](scripts/ci/lme_ci.py) assert the editable extension's version and environment path, then build, install, assert, and test the wheel in a separate locked environment. Pull-request/tag CI runs that full identity flow on Python **3.11**, tests isolated wheels on Python **3.10–3.13** on Ubuntu, and tests isolated Python 3.11 wheels on Windows and macOS (jobs `python-bindings-versions` and `python-bindings-os` in [`.github/workflows/ci.yml`](.github/workflows/ci.yml)). If you use **CPython 3.14** locally, set `PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1` before `maturin develop` (see [python/PYTHON_GUIDE.md](python/PYTHON_GUIDE.md)).
+[`task python`](Taskfile.yml) / [`scripts/ci/lme_ci.py python`](scripts/ci/lme_ci.py) assert the editable extension's version and environment path, then build, install, assert, and test the wheel in a separate locked environment. `task consumer:smoke` adds a dependency-only clean environment and runs the portable examples against the installed wheel. Pull-request/tag CI runs the full identity and consumer-example flow on Python **3.11**, tests isolated wheels on Python **3.10–3.13** on Ubuntu, and runs the consumer examples against isolated Python 3.11 wheels on Windows and macOS (jobs `python-bindings-versions` and `python-bindings-os` in [`.github/workflows/ci.yml`](.github/workflows/ci.yml)). If you use **CPython 3.14** locally, set `PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1` before `maturin develop` (see [python/PYTHON_GUIDE.md](python/PYTHON_GUIDE.md)).
 
 ## Working on numerical changes
 
@@ -163,7 +166,7 @@ Do not describe a feature as supported unless it is exposed by the public API an
 - [`.github/workflows/audit.yml`](.github/workflows/audit.yml) — a required release-CI gate running `cargo audit` on the root and `python/` Rust crates plus `pip-audit` on the [`python/uv.lock`](python/uv.lock) dev environment; it also runs weekly and supports manual dispatch.
 - [`.github/workflows/fuzz-smoke.yml`](.github/workflows/fuzz-smoke.yml) — weekly and manually dispatched libFuzzer coverage for formula parsing and the formula-to-matrix pipeline.
 - [`.github/workflows/crate-publish-dry-run.yml`](.github/workflows/crate-publish-dry-run.yml) — called by release CI to publish only after the full tag matrix succeeds; manual dispatch runs `cargo publish --dry-run --locked` only.
-- [`.github/workflows/python-release.yml`](.github/workflows/python-release.yml) — called by release CI to build and publish only after the full tag matrix succeeds; manual dispatch builds artifacts without publishing.
+- [`.github/workflows/python-release.yml`](.github/workflows/python-release.yml) — dispatched as a top-level workflow by release CI to verify the tag/SHA, build, and publish only after the full tag matrix succeeds; ordinary manual dispatch builds artifacts without publishing.
 
 Pull requests automatically run CI. Ordinary non-PR branch pushes do not start workflows; use Lefthook and Task locally before pushing, and use manual dispatch when a remote check is useful before tagging.
 

{lme_python-0.2.1 → lme_python-0.2.2}/Cargo.lock

@@ -1508,7 +1508,7 @@ checksum = "11d3d7f243d5c5a8b9bb5d6dd2b1602c0cb0b9db1621bafc7ed66e35ff9fe092"
 
 [[package]]
 name = "lme-rs"
-version = "0.2.1"
+version = "0.2.2"
 dependencies = [
  "ahash",
  "anyhow",

{lme_python-0.2.1 → lme_python-0.2.2}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "lme-rs"
-version = "0.2.1"
+version = "0.2.2"
 edition = "2021"
 authors = ["Martin Huck <x4g4p3x@users.noreply.github.com>"]
 description = "Rust port of R's lme4: linear, generalized, and nonlinear mixed-effects models"