nanbeige-mlx
An MLX port of the Nanbeige4.2-3B Looped Transformer for Apple Silicon,
plus the HF→MLX conversion and publishing helpers. The model definition in
nanbeige_mlx/model.py is the single source of truth
for the port — it is also copied verbatim into each converted weight directory
as the model_file mlx-lm loads.
This is an independent project; it is not affiliated with or endorsed by the Nanbeige team.
What's here
| module | purpose |
|---|---|
nanbeige_mlx/model.py |
the port — also the shipped model_file |
nanbeige_mlx/convert.py |
HF → MLX quant (non-mutating staging, tokenizer verify) |
nanbeige_mlx/upload.py |
model-card + LICENSE + NOTICE + (opt-in) HF upload |
nanbeige_mlx/pull.py |
pull("4bit") → local path for mlx_lm.load |
Load a published quant (one line)
from nanbeige_mlx import pull
import mlx_lm
model, tok = mlx_lm.load(pull("4bit"))
Convert from the BF16 checkpoint yourself
nanbeige-mlx-convert --src /path/to/Nanbeige4.2-3B --out ./nanbeige-mlx-4bit --bits 4
The source directory is never mutated; the tokenizer round-trip is asserted.
The 44-slot KV cache (a real cost of the looped design)
The looped architecture needs num_loops * num_hidden_layers = 44 KV slots.
At full context that is 44 × 8 KV-heads × 128 dim × 2 (K+V) × 262 144 positions
× 2 bytes ≈ 47 GB — unreachable on a 16 GB machine. Because this model
supplies make_cache, mlx-lm's --max-kv-size knob is inert; use --kv-bits
to reduce KV precision instead. This is a quantifiable cost of the looped
design, not a bug — see make_cache()'s docstring.
Dependencies
Upper-bounded to mlx>=0.32,<0.34 and mlx-lm>=0.31,<0.33. The bounds are
deliberate: model.py uses mlx_lm.models.base / .cache internals and is
copied verbatim into every published weight repo as the model_file, where it
is frozen — a user who already downloaded a quant cannot receive a patch.
Relaxing the bound is a decision to make after testing against a new mlx-lm.
Fidelity status
This port is validated by behaviour, not bit-parity: per-layer arithmetic
agrees with the reference's own NanbeigeDecoderLayer to fp32 precision, the
44-slot loop-aware KV cache passes a prefill-vs-incremental-decode equality
test, and the port's two code paths are bit-identical. End-to-end next-token
logit cosine against the HF reference is 0.847 (top-1 agreement 83%), lower
than a faithful port should give; six candidate causes have been eliminated by
measurement. The full record — including every falsified hypothesis — is in
the evaluation harness repo's
docs/investigation-log.md.
Behaviour on the bilingual agentic suite is unaffected (26–28/30 across
4/6/8-bit).
License
MIT for the code in this package. The Nanbeige model weights are governed by the upstream Apache-2.0 license; convert and redistribute them per that license.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file nanbeige_mlx-0.2.0.tar.gz.
File metadata
- Download URL: nanbeige_mlx-0.2.0.tar.gz
- Upload date:
- Size: 23.9 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
f123d2f4a15768d7a46ab188e05ec9d87e1bcb2650f654cc5e40f7e2c798c6aa
|
|
| MD5 |
16ad105cb4cf388ba8674e10b122a1aa
|
|
| BLAKE2b-256 |
7d9d3ee009a8eead416ab6fc22e9c9c597ff03adfe54fd8d6043cc6b578aea78
|
Provenance
The following attestation bundles were made for nanbeige_mlx-0.2.0.tar.gz:
Publisher:
publish.yml on jishnuvenugopal/nanbeige-mlx
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
nanbeige_mlx-0.2.0.tar.gz -
Subject digest:
f123d2f4a15768d7a46ab188e05ec9d87e1bcb2650f654cc5e40f7e2c798c6aa - Sigstore transparency entry: 2267732487
- Sigstore integration time:
-
Permalink:
jishnuvenugopal/nanbeige-mlx@a5b208903bdaf8f18fa853e91b5035c62116f4a6 -
Branch / Tag:
refs/tags/v0.2.0 - Owner: https://github.com/jishnuvenugopal
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@a5b208903bdaf8f18fa853e91b5035c62116f4a6 -
Trigger Event:
push
-
Statement type:
File details
Details for the file nanbeige_mlx-0.2.0-py3-none-any.whl.
File metadata
- Download URL: nanbeige_mlx-0.2.0-py3-none-any.whl
- Upload date:
- Size: 23.1 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
9bce3072906a2cc91079ef6abedf3991b49664ae7a81d4c1495cf10cf8e5c694
|
|
| MD5 |
abfc92b1254c251ab6fb6f8bb0c5685d
|
|
| BLAKE2b-256 |
16fe9a94156e5e8f41f3a66fc7ef907ff3cc9e940a7b3215d0060f37fb8c4765
|
Provenance
The following attestation bundles were made for nanbeige_mlx-0.2.0-py3-none-any.whl:
Publisher:
publish.yml on jishnuvenugopal/nanbeige-mlx
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
nanbeige_mlx-0.2.0-py3-none-any.whl -
Subject digest:
9bce3072906a2cc91079ef6abedf3991b49664ae7a81d4c1495cf10cf8e5c694 - Sigstore transparency entry: 2267732558
- Sigstore integration time:
-
Permalink:
jishnuvenugopal/nanbeige-mlx@a5b208903bdaf8f18fa853e91b5035c62116f4a6 -
Branch / Tag:
refs/tags/v0.2.0 - Owner: https://github.com/jishnuvenugopal
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@a5b208903bdaf8f18fa853e91b5035c62116f4a6 -
Trigger Event:
push
-
Statement type:
