Skip to content

armgit / laya

Public Imported from GitHub
0

Non-autoregressive System 1 decision engine. Typed choice, score and yes/no decisions over any text in a single forward pass, in 100+ languages, with a router that picks the right checkpoint per request.

feat(setup): a macOS/Intel checkout setup and verification path

thread3d79644017cd5c
diff --git a/.gitignore b/.gitignore
index 75442a6f..3affe912 100644
--- a/.gitignore
+++ b/.gitignore
@@ -32,8 +32,20 @@ node_modules/
.DS_Store
.env
.pypirc
+.ruff_cache/
.idea/
+# local setup artifacts from setup_laya.sh: ~2.3 GB of checkpoint weights and the download caches
+models/
+.hf-cache/
+.pip-cache/
+
+# outputs written by the research/scripts harnesses; curated runs live in research/results/
+research/*_benchmark_results.json
+
+# output of a local notebook run (Kaggle uses /kaggle/working)
+notebooks/finetune_run/
+
# session transcripts (may contain pasted credentials)
session-*.md
diff --git a/LOCAL_SETUP.md b/LOCAL_SETUP.md
new file mode 100644
index 00000000..68ec6d1a
--- /dev/null
+++ b/LOCAL_SETUP.md
@@ -0,0 +1,262 @@
+# Laya on this machine — local setup
+
+Laya (the checkout in `laya/`) now runs here on real weights: all three checkpoints, real forward
+passes, on CPU and on the AMD GPU through Metal (MPS). This file records what was installed, the
+two code changes that were needed, how to re-run everything, and the numbers that were measured.
+
+## Host
+
+| | |
+|---|---|
+| machine | `MacPro7,1` (2019 Mac Pro), Intel Xeon, 56 logical cores, 256 GB RAM |
+| OS | macOS (Darwin 25.6.0), `x86_64` |
+| GPU | AMD Radeon Pro Vega II (32 GB) + Radeon PRO W6800X Duo, Metal 3 |
+| accelerator APIs | **no CUDA** — CPU, or MPS via Metal |
+
+## What was installed (all inside the repository; everything below is gitignored)
+
+| path | contents |
+|---|---|
+| `.venv/` | Python 3.11.5 virtualenv — torch 2.2.2, transformers 4.57.6, numpy 1.26.4, safetensors 0.8.0, huggingface_hub 0.36.2 |
+| `models/` | the three checkpoints (~2.3 GB): `laya/` (English), plus `laya-multilingual` and `laya-typed-decisions` symlinked into the bundle |
+| `.pip-cache/`, `.hf-cache/` | download caches, kept local so nothing is written outside the project |
+| `setup_laya.sh` | idempotent setup: venv → pinned deps → editable install → checkpoints → verify |
+| `verify/laya_smoke_test.py` | end-to-end check on real weights: routing, all three checkpoints, all three primitives, presets, latency |
+| `verify/numerics_check.py` | RoPE base actually used vs. trained, run-to-run determinism, SDPA vs. eager |
+| `verify/bench_devices.py` | CPU vs. MPS latency, plus CPU thread scaling |
+| `verify/edge_sweep.py` | inference paths the other suites miss: 12 questions in one pass, 20/77/120-option choice, odd input shapes, truncation, router lifecycle, CPU-vs-MPS agreement |
+| `verify/checkpoints.py` + `verify/checkpoints.json` | checks the weights against recorded sha256 hashes (a truncated download is otherwise silently wrong) |
+| `verify/soak_check.py` | 200 repeated calls for drift and RSS growth, reload/eviction cycles, concurrent calls from several threads. Uses `psutil` if installed and falls back to peak RSS otherwise |
+| `examples/` | 41 worked examples as an eight-stage learning path, plus `run_all.sh` and the path doc |
+
+`laya` is installed editable, so `import laya` from anywhere uses this checkout and picks up edits.
+
+## Code changes that were required
+
+The first two are real portability bugs, not local hacks; both are covered by
+`tests/test_portability.py` (18 checks, including the CUDA-OOM fallback), which is wired into
+CI along with `tests/test_training.py`.
+
+### 1. `laya/common.py` — transformers 5 checkpoints on transformers 4
+
+The checkpoints were saved by transformers 5, which records ModernBERT's RoPE bases as
+`rope_parameters = {"full_attention": {...}, "sliding_attention": {...}}`. transformers 4.x does
+not read that key, so it silently keeps its own defaults — global `160000`, local `10000`:
+
+* `laya` and `laya-typed-decisions` want `160000 / 10000` → they happened to match.
+* `laya-multilingual` (mmBERT) wants `160000 / 160000` → it ran with the **wrong RoPE base** on
+ every sliding-attention layer, with no error. This is the "quietly wrong numbers" class of bug.
+
+`build_model()` now maps `rope_parameters` onto the `global_rope_theta` / `local_rope_theta`
+attributes that 4.x reads (and that the upstream `jhu-clsp/mmBERT-base` config still uses). On
+transformers 5 the function is a no-op. Effect on the multilingual checkpoint, same input:
+
+| | before | after |
+|---|---|---|
+| Hindi "charged twice, refund" → `billing` | 0.8647 | **0.9328** |
+| Hindi → `refund_requested` | 0.9897 | 0.9909 |
+| English / typed-decisions outputs | — | **bit-identical** (their configs already matched) |
+
+### 2. `laya/agent.py` — MPS crashed every call
+
+`system_one` entered `torch.autocast(device_type=self.device.type, enabled=use_amp)` on every
+call. Autocast is only ever *enabled* on CUDA, but torch validates the device type regardless, and
+torch has no MPS autocast backend:
+
+```
+RuntimeError: User specified an unsupported autocast device_type 'mps'
+```
+
+Laya selects MPS automatically when it is available, so on this machine every `predict()` raised.
+The forward pass now goes through `_amp_context(device, dtype)`, which returns
+`torch.autocast(..., "cuda")` on CUDA and a `nullcontext()` otherwise.
+
+### 3. Smaller fixes found while verifying
+
+* **`collate_items` failed unhelpfully on malformed training data.** A target with more entries
+ than the item has markers died inside a tensor assignment with *"The expanded size of the tensor
+ (k) must match the existing size (kmax)"*, which says nothing about the mistake. It now raises a
+ `ValueError` naming the item and both counts, and `tests/test_training.py` asserts that.
+* **`Router.load()` does not evict on a cache hit.** Asking for a checkpoint that is already
+ resident returns early, so `max_loaded` is enforced when a checkpoint is *loaded* rather than
+ when one is touched. The behaviour is unchanged — it is now stated in the docstring, because
+ lowering `max_loaded` after a `preload` does not free anything until the next miss.
+
+## Verify it
+
+```bash
+cd /Users/threaded/projects/Laya/laya # repository root
+./setup_laya.sh # venv + deps + checkpoints + smoke test (idempotent)
+
+# or individually
+.venv/bin/python verify/laya_smoke_test.py --models ./models # device auto → MPS
+.venv/bin/python verify/laya_smoke_test.py --models ./models --device cpu
+.venv/bin/python verify/numerics_check.py
+.venv/bin/python verify/bench_devices.py
+.venv/bin/python verify/edge_sweep.py
+.venv/bin/python verify/checkpoints.py # weights vs recorded hashes
+.venv/bin/python verify/soak_check.py # drift, RSS, concurrency
+.venv/bin/python tests/test_local_e2e.py ./models # the repo's own e2e suite
+./examples/run_all.sh # every example, one log per run
+```
+
+Results on this machine:
+
+| check | result |
+|---|---|
+| `tests/test_local_e2e.py` (real weights, CPU) | **23 passed, 0 failed** — multilingual billing 8/8, all 11 routing languages correct |
+| `tests/test_router.py` | 106 passed, 0 failed |
+| `tests/test_criteria.py` | 34 passed, 0 failed |
+| `tests/test_portability.py` | 18 passed, 0 failed (includes the CUDA-OOM fallback) |
+| `verify/laya_smoke_test.py` | all checks passed on **both** CPU and MPS |
+| `verify/numerics_check.py` | RoPE bases match training; answers bit-identical run-to-run and SDPA vs. eager (`0.00e+00` on every reported value) |
+| `verify/edge_sweep.py` | all edge-case checks pass (25 here; the MPS checks skip where MPS is unavailable) |
+| `verify/checkpoints.py` | 3/3 checkpoints match the recorded sha256; a deliberately corrupted copy is caught |
+| `verify/soak_check.py` | 200/200 calls byte-identical with flat RSS; 6 reload cycles leave exactly 1 live agent and 1 live model (0 after `unload()`); 4-thread concurrency matches the single-threaded answer |
+| `tests/test_training.py` | 59 passed — proper-scoring-rule reward, TD(λ) targets, ECE, entropy confidence, collation, sequence building |
+| `examples/run_all.sh` | **41 passed, 0 failed** (eight stages, 23-49 s each; the whole sweep is ~20 min) |
+| CI lint (`ruff`) + `compileall` | pass |
+
+CPU and MPS produce identical answers (same presets, same confidences), so the GPU path is not a
+numerical downgrade.
+
+## Measured performance
+
+One `predict()` call answering 4 questions on a short email, median of 10 after warm-up:
+
+| checkpoint | CPU (28 threads) | MPS (Radeon Pro Vega II) |
+|---|---|---|
+| `laya` (421M) | 453 ms — 113 ms/question | **146 ms — 37 ms/question** |
+| `laya-multilingual` (322M) | 192 ms — 48 ms/question | **121 ms — 30 ms/question** |
+| `laya-typed-decisions` (421M) | 441 ms — 110 ms/question | **145 ms — 36 ms/question** |
+
+Re-measured on a quiet machine for the final verification pass; individual runs move by a few
+percent with machine load (an earlier pass gave 424/195/427 ms on CPU and 141/117/142 ms on MPS).
+
+The GPU is 1.6-3× faster than this 56-core CPU (3× on the two ModernBERT-large checkpoints, 1.6×
+on the smaller multilingual one). The README's T4 reference is 32.8 ms/question for
+`laya-multilingual`; MPS lands at 29 ms/question, i.e. T4-class latency on this hardware.
+
+CPU thread scaling on `laya` (medians): 4 → 501 ms, 8 → 385 ms, **16 → 366 ms**, 28 → 415 ms,
+56 → 1266 ms. Around 16 threads is the sweet spot; the default 28 already over-subscribes and 56
+threads is markedly worse, so `OMP_NUM_THREADS=16` (or `torch.set_num_threads(16)`) is worth
+setting for CPU-only work.
+
+The ONNX Runtime path is faster than torch eager on the same CPU: one `predict()` answering 3
+questions drops from 489 ms to **331 ms (1.48×)** in fp32, bit-identical to eager, and to
+**170 ms (2.9×)** with the opt-in per-channel INT8 copy, which moves probabilities by up to
+0.16. Installing the `onnx` extra on this stack also wants `numpy<2`, since torch below 2.3
+cannot convert tensors against NumPy 2.
+
+Notes: the first MPS call pays ~13 s of Metal kernel compilation, so warm up before timing;
+everything runs fp32 (bf16 autocast is CUDA-only in Laya).
+
+## Independent accuracy check against public data
+
+Setting the machine up only proved the plumbing worked. The published tables were re-checked by
+running the repo's own harnesses against public datasets — this is measured here, CPU only, not
+copied from `BENCHMARKS.md`.
+
+### MASSIVE intent, 20 options — `research/scripts/bench_local.py --langs 10 --per-lang 60 --skip-b`
+
+| | english | multilingual | published, 51 languages (english / multilingual) |
+|---|---|---|---|
+| macro accuracy | 0.2500 | **0.3950** | 0.2269 / 0.3661 |
+| macro ECE *(lower better)* | 0.7100 | **0.4008** | 0.7331 / 0.3869 |
+| languages > 3x random | 4 / 10 | **8 / 10** | 23 / 51 / 45 / 51 |
+
+Per language, `en` scores **0.783** — the published English figure exactly — and the English
+checkpoint then collapses off English *while staying confident*: Amharic 0.100 at 0.949 mean
+confidence, Arabic 0.133 at 0.897, Bengali 0.117 at 0.953, Greek 0.150 at 0.970. The multilingual
+checkpoint holds those up (Arabic 0.450, Bengali 0.450, Greek 0.417, German 0.467), which is the
+whole reason `Router` exists.
+
+### Applications — `research/scripts/bench_apps.py` with `BENCH_N=80`
+
+| suite | english | multilingual | typed-decisions | README (routed) |
+|---|---|---|---|---|
+| AG News, 4 labels | 0.963 | **0.975** | 0.963 | 0.950 |
+| DAIR Emotion, 6 labels | 0.637 | 0.600 | **0.662** | 0.595 |
+| Banking77, 77 labels at once | 0.412 | 0.500 | 0.425 | 0.425 |
+| phishing email | 0.975 | **0.988** | 0.925 | — |
+| email spam | **0.988** | 0.963 | 0.925 | — |
+| guardrails (jailbreak) | 0.838 | **0.875** | 0.863 | 0.698 (injections) |
+| moderation (toxicity) | 0.500 | 0.487 | 0.500 | — |
+| support triage | 0.550 | 0.550 | 0.537 | — |
+
+Banking77 lands on **0.425**, the number the README quotes for the 77-option case, and the
+AG News / emotion figures agree with the published routed results within sampling noise (80 cases
+per suite here). The README's honest limits reproduce too: `score` is the weakest primitive and
+50+ options in one question is where Laya trails Jev.
+
+Both tables were re-run end to end a second time (same seed, same cached datasets) and
+reproduced **identically — every accuracy, F1 and ECE digit, and both macro aggregates**. The
+runs are deterministic; only the ms/case figures move with machine load.
+
+### Two fixes the harnesses needed to run here
+
+* they hardcoded the model root to `~/laya_models` — now `LAYA_MODELS` (default unchanged), so
+ `LAYA_MODELS=$PWD/models` points them at the checkpoints this repo already has;
+* their `sys.path` insert pointed at a non-existent `research/laya`; it now points at the
+ repository root.
+
+### What the soak check found
+
+Repeated checkpoint loads push RSS up and it never comes back down — after 6 reload cycles the
+process sat at 3.4 GB against 2.3 GB for a single resident checkpoint, and `unload()` did not
+return it. That is macOS `malloc` keeping freed pages, not a leak: counting live objects shows
+**exactly 1 `Agent` and 1 `DecisionModel` while cycling and 0 after `unload()`**, which is what
+the check now asserts.
+
+The same exercise threw up an API subtlety worth knowing: `Router.load()` returns early for a
+checkpoint that is already resident, so it does not run eviction. `max_loaded` is enforced when a
+checkpoint is *loaded*, not when one is touched — lower it and then load something new, or call
+`unload()`, if residency has to drop immediately. That is now stated in `Router.load`'s docstring.
+
+## Using it from your own code
+
+The checkpoints are already on disk, so point the router at the local roots and nothing touches
+the network:
+
+```python
+import laya
+from laya import Router
+
+root = "/Users/threaded/projects/Laya/laya/models"
+router = Router(models={"english": root + "/laya",
+ "multilingual": root + "/laya-multilingual",
+ "typed-decisions": root + "/laya-typed-decisions"},
+ preload=True) # device=None → MPS here; pass device="cpu" to force CPU
+
+res = router.predict({"body": "发票4411被重复扣款,请今天退款。"}, laya.triage_questions())
+print(res["routing"]["model"], res["answers"]["intent"]["choice"])
+```
+
+`laya.load("<path>", device="mps")` works the same way for a single checkpoint. Leaving `device`
+unset picks MPS, then CPU.
+
+## Why these versions
+
+* **torch 2.2.2** is the newest PyTorch with a macOS `x86_64` wheel. Both PyPI and
+ `download.pytorch.org` stop at 2.2.2 (2.3.0 onward are Apple-Silicon-only), which is the whole
+ constraint chain here.
+* **transformers 4.57.6** is the last 4.x line. transformers 5.x requires torch ≥ 2.4, so it
+ cannot be used with the only torch this CPU can install — hence the RoPE mapping above. 4.57.x
+ is also the line that reads both ModernBERT and mmBERT checkpoints.
+* **numpy < 2** because torch 2.2.2 was compiled against NumPy 1.x and fails to initialise under
+ NumPy 2 (`Failed to initialize NumPy: _ARRAY_API not found`).
+* **huggingface_hub < 1.0** is pinned by transformers 4.x.
+
+If a newer torch is ever wanted, conda-forge still builds `osx-64` PyTorch (CPU/MKL) past 2.13,
+which would allow transformers 5.x and remove the need for the RoPE mapping. That is an
+alternative, not what is installed and verified here.
+
+## Caveats
+
+* No CUDA: fp16/bf16 mixed precision is unavailable, CPU and MPS both run fp32.
+* MPS is a torch 2.2-era backend on Intel AMD hardware — it works and matches CPU numerics here,
+ but it is not an NVIDIA-class path. `--device cpu` is the conservative choice.
+* `models/` is ~2.3 GB and `.venv/` ~1 GB; both live in the repository and are gitignored, so
+ they can be deleted and rebuilt with `./setup_laya.sh` without touching the working tree.
+* No TensorFlow is installed on purpose (`USE_TF=0`): a TF install alongside torch can deadlock
+ model construction, which the repo's tests already guard against.
diff --git a/README.md b/README.md
index 9c701422..bd032d1b 100644
--- a/README.md
+++ b/README.md
@@ -197,6 +197,16 @@ Three checkpoints, and a `Router` that picks between them per request:
| [`laya-multilingual`](https://huggingface.co/convaiinnovations/laya-multilingual) | mmBERT-base | 322M | 1024 (up to 8,192) | 100+ languages, 2x faster |
| [`laya-typed-decisions`](https://huggingface.co/convaiinnovations/laya-typed-decisions) | ModernBERT-large | 421M | 1024 | the typed-decisions workflows |
+## Where to go next
+
+| document | what is in it |
+|---|---|
+| Quickstart below | the shortest path to a working call |
+| [`examples/README.md`](https://github.com/NandhaKishorM/laya/blob/main/examples/README.md) | 41 runnable examples as an eight-stage learning path: first call → schema design → production service |
+| [`LOCAL_SETUP.md`](https://github.com/NandhaKishorM/laya/blob/main/LOCAL_SETUP.md) | running this checkout on macOS/Intel: pinned stack, checkpoint manifest, the two portability fixes, every verification run and its result |
+| [`BENCHMARKS.md`](https://github.com/NandhaKishorM/laya/blob/main/BENCHMARKS.md) | every benchmark run consolidated, all 51 languages, with the limits stated plainly |
+| [`research/README.md`](https://github.com/NandhaKishorM/laya/blob/main/research/README.md) | the harnesses that produce those numbers, and how to re-run them |
+
## Installation details
@@ -350,6 +360,82 @@ checkpoint goes from 24/58 correct at its default 192-token option budget to 34/
accuracy back, because `max_len` then leaves fewer tokens for the request itself. [Honest
limits](#honest-limits) describes the same budget ceiling for a 77-option question.
+Device selection is automatic, in this order: **CUDA → MPS → CPU**. Mixed precision is used on
+CUDA; CPU and MPS run fp32. Override with `device=`, which is accepted by both entry points:
+
+```python
+agent = laya.load("convaiinnovations/laya", device="cpu") # or "cuda", "mps"
+router = Router(preload=True, device="mps")
+```
+
+### macOS, including Intel Macs
+
+PyTorch stops publishing macOS **x86_64** wheels at 2.2.2 (2.3 and later are Apple-silicon only),
+while transformers 5.x requires torch >= 2.4 and torch 2.2.2 was built against NumPy 1.x. A plain
+`pip install laya` on an Intel Mac therefore resolves a stack that cannot run — torch 2.2.2 with
+transformers 5.x and NumPy 2.x, and torch fails to initialise NumPy 2, which `predict()` needs for
+its final `.numpy()` conversion. Pin the stack:
+
+```bash
+pip install "numpy<2" "torch==2.2.2" "transformers==4.57.6" laya
+```
+
+`transformers` 4.57.x is the last 4.x line and the newest one that runs on torch 2.2.2. The
+transformers-5 checkpoints load on it unchanged: `build_model` maps their `rope_parameters` onto
+the RoPE attributes 4.x reads, which mmBERT needs because both of its bases are 160000 rather
+than the 4.x defaults. Apple-silicon and CUDA machines need none of this pinning.
+
+---
+
+## Running from this checkout
+
+`setup_laya.sh` stands the whole thing up in the checkout: an isolated `.venv` with the pinned
+stack, the three checkpoints under `models/` (gitignored, ~2.3 GB), and a verification run. It is
+idempotent, so re-running only fills in what is missing. The numbers below are from the machine it
+was developed on — an Intel Mac Pro, no CUDA, AMD Radeon GPUs reachable through Metal (MPS); the
+script itself is not Intel-specific. Commands are relative to the repository root.
+
+```bash
+./setup_laya.sh # venv + pinned deps + checkpoints + verify
+.venv/bin/python verify/laya_smoke_test.py --models ./models # real weights, device auto -> MPS
+.venv/bin/python verify/laya_smoke_test.py --models ./models --device cpu
+.venv/bin/python verify/numerics_check.py # RoPE bases, determinism, SDPA vs eager
+.venv/bin/python verify/bench_devices.py # CPU vs MPS, thread scaling
+.venv/bin/python verify/edge_sweep.py # edge cases: option budgets, truncation, router lifecycle
+.venv/bin/python verify/checkpoints.py # weights vs the recorded sha256 hashes
+.venv/bin/python verify/soak_check.py # drift, RSS and concurrency over 200 calls
+.venv/bin/python tests/test_local_e2e.py ./models # the repo's own e2e suite
+./examples/run_all.sh # all 41 examples, pass/fail
+```
+
+Measured here, one `predict()` call answering 4 questions about a short email (median of 10,
+after warm-up):
+
+| checkpoint | CPU (28 threads) | MPS (Radeon Pro Vega II) |
+|---|---|---|
+| `laya` (421M) | 453 ms — 113 ms/question | **146 ms — 37 ms/question** |
+| `laya-multilingual` (322M) | 192 ms — 48 ms/question | **121 ms — 30 ms/question** |
+| `laya-typed-decisions` (421M) | 441 ms — 110 ms/question | **145 ms — 36 ms/question** |
+
+MPS is 1.6-3x this 56-core CPU and matches the T4 reference quoted below (32.8 ms/question for
+`laya-multilingual`). CPU-only work runs fastest around 16 threads (`OMP_NUM_THREADS=16`); the
+default 28 already over-subscribes. The first MPS call pays ~13 s of Metal kernel compilation,
+so warm up before timing. Individual runs move by a few percent with machine load.
+
+To keep the router fully offline, point it at the local checkpoints rather than the hub repos:
+
+```python
+from laya import Router
+
+router = Router(models={"english": "models/laya",
+ "multilingual": "models/laya-multilingual",
+ "typed-decisions": "models/laya-typed-decisions"},
+ preload=True)
+```
+
+Full notes — version rationale, the two portability fixes this needed, and every verification
+run — are in [`LOCAL_SETUP.md`](https://github.com/NandhaKishorM/laya/blob/main/LOCAL_SETUP.md).
+
---
## Try it locally: web GUI + JSON API
@@ -607,7 +693,7 @@ For a server or production app, preload:
```python
# Every checkpoint resident in memory; language flips cost detection only (<1 ms)
router = Router(preload=True)
-router = Router(preload=True, device="cuda")
+router = Router(preload=True, device="cuda") # or "mps" (Apple/AMD GPU), "cpu" to force
# Or preload only the specific checkpoints you serve:
router.preload(["english", "multilingual"])
diff --git a/setup_laya.sh b/setup_laya.sh
new file mode 100755
index 00000000..4d272aca
--- /dev/null
+++ b/setup_laya.sh
@@ -0,0 +1,108 @@
+#!/usr/bin/env bash
+# Reproducible local setup for Laya on this machine (macOS on Intel x86_64).
+#
+# Creates an isolated virtualenv, installs the only PyTorch release that still ships a
+# macOS Intel wheel, installs the newest transformers that runs on it, downloads the three
+# Laya checkpoints, and verifies the result with a real forward pass.
+#
+# Usage: ./setup_laya.sh [--skip-models] [--skip-verify]
+# Idempotent: re-running only fixes what is missing.
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" # repository root
+VENV="$ROOT/.venv"
+PYTHON_BIN="${PYTHON:-python3}"
+
+# Keep every byte this setup writes inside the project directory.
+export PIP_CACHE_DIR="$ROOT/.pip-cache"
+export HF_HOME="$ROOT/.hf-cache"
+export HF_HUB_DISABLE_TELEMETRY=1
+export TOKENIZERS_PARALLELISM=false
+export USE_TF=0 # Laya is torch-only; a stray TensorFlow install can deadlock loading
+export USE_TORCH=1
+
+SKIP_MODELS=0
+SKIP_VERIFY=0
+for arg in "$@"; do
+ case "$arg" in
+ --skip-models) SKIP_MODELS=1 ;;
+ --skip-verify) SKIP_VERIFY=1 ;;
+ *) echo "unknown option: $arg" >&2; exit 2 ;;
+ esac
+done
+
+say() { printf '\n\033[1m==> %s\033[0m\n' "$*"; }
+
+say "Host"
+uname -srm
+"$PYTHON_BIN" -c 'import platform,sys;print("python", sys.version.split()[0], platform.machine())'
+
+if [ "$(uname -s)" != "Darwin" ]; then
+ echo "warning: this script targets macOS; continuing anyway" >&2
+fi
+
+say "Virtualenv at $VENV"
+if [ ! -x "$VENV/bin/python" ]; then
+ "$PYTHON_BIN" -m venv "$VENV"
+fi
+"$VENV/bin/python" -m pip install --quiet --upgrade pip
+
+say "Dependencies"
+# torch: PyPI and download.pytorch.org both stopped publishing macOS x86_64 wheels after
+# 2.2.2, so this is the newest PyTorch this CPU can run from a wheel.
+# numpy: torch 2.2.2 was compiled against NumPy 1.x and fails to initialise under NumPy 2.
+# transformers: 4.57.x is the last 4.x line (5.x requires torch>=2.4, unavailable here) and
+# the oldest line that reads both the ModernBERT and mmBERT checkpoints.
+# huggingface_hub is capped <1.0 by transformers 4.x.
+"$VENV/bin/python" -m pip install \
+ "numpy<2" \
+ "torch==2.2.2" \
+ "transformers==4.57.6" \
+ "safetensors>=0.4.0" \
+ "huggingface_hub>=0.34.0,<1.0"
+
+say "Installing the laya package (editable)"
+"$VENV/bin/python" -m pip install --quiet -e "$ROOT"
+
+if [ "$SKIP_MODELS" -eq 0 ]; then
+ say "Checkpoints -> $ROOT/models"
+ if [ -f "$ROOT/models/laya/model.safetensors" ]; then
+ echo "already present, skipping download"
+ else
+ # One repo bundles all three checkpoints; ~2.3 GB of safetensors.
+ ( cd "$ROOT" && "$VENV/bin/python" - <<'PY'
+from huggingface_hub import snapshot_download
+p = snapshot_download(
+ "convaiinnovations/laya",
+ local_dir="models/laya",
+ allow_patterns=["*.json", "*.safetensors", "*.txt", "tokenizer.json"],
+)
+print("downloaded ->", p)
+PY
+ )
+ fi
+ # tests/test_local_e2e.py expects <root>/{laya,laya-multilingual,laya-typed-decisions};
+ # the bundle ships the two extra checkpoints as subfolders of the first.
+ ln -sfn laya/multilingual "$ROOT/models/laya-multilingual"
+ ln -sfn laya/typed-decisions "$ROOT/models/laya-typed-decisions"
+ ls -l "$ROOT/models"
+fi
+
+# A truncated or silently-updated download turns into quietly wrong answers, so check the weights
+# against the hashes recorded in verify/checkpoints.json. Runs whenever the weights are there,
+# including on a --skip-models re-run.
+if [ -f "$ROOT/models/laya/model.safetensors" ]; then
+ say "Checking checkpoint integrity"
+ "$VENV/bin/python" "$ROOT/verify/checkpoints.py" --models "$ROOT/models"
+elif [ "$SKIP_MODELS" -eq 0 ]; then
+ echo "warning: models/laya/model.safetensors is still missing" >&2
+fi
+
+if [ "$SKIP_VERIFY" -eq 0 ]; then
+ say "Verifying with real weights"
+ "$VENV/bin/python" "$ROOT/verify/laya_smoke_test.py" --models "$ROOT/models"
+fi
+
+say "Done"
+echo "Activate with: source \"$VENV/bin/activate\""
+echo "Run the suite: python tests/test_local_e2e.py \"$ROOT/models\""
diff --git a/tests/test_packaging.py b/tests/test_packaging.py
index 602b0ec8..6b5e8d94 100644
--- a/tests/test_packaging.py
+++ b/tests/test_packaging.py
@@ -250,9 +250,11 @@ def _headings(path):
_md = []
for _dirpath, _dirnames, _filenames in os.walk("."):
# `.pytest_cache` ships a README of its own and `.venv` is where CONTRIBUTING tells
- # contributors to install; neither is part of the repository.
+ # contributors to install; neither is part of the repository. `.hf-cache` holds
+ # third-party dataset cards downloaded by setup_laya.sh (gitignored).
_dirnames[:] = [d for d in _dirnames
- if d not in (".git", "__pycache__", "node_modules", ".pytest_cache", ".venv")]
+ if d not in (".git", "__pycache__", "node_modules", ".pytest_cache",
+ ".venv", ".hf-cache")]
_md.extend(os.path.normpath(os.path.join(_dirpath, f))
for f in _filenames if f.endswith(".md"))
_md = sorted(_md)