funasr-mlx 0.1.0__tar.gz

funasr_mlx-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+.venv/
+.tmp/
+.pi/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+*.egg-info/
+build/
+dist/
+checkpoints/
+*.safetensors
+*.npz
+.DS_Store

funasr_mlx-0.1.0/AGENTS.md

@@ -0,0 +1,13 @@
+# Development Rules
+
+Reference repository: `/Users/baicai1145/repos/funasr` (read-only).
+
+- Port inference semantics from the exact FunASR source, including masking, layout, padding, epsilon, and checkpoint key names. No PyTorch inference dependency.
+- Absolute memory ceiling is 12,000,000,000 bytes. Leave headroom: use small synthetic dimensions only. Never load/download full weights or run MLX/PyTorch numerical tests without lead approval. All expensive verification is serialized by the lead through the memory guard.
+- Agents implement and use syntax/static checks only unless explicitly authorized. Maximum two concurrent implementation agents. Do not launch other agents.
+- Runtime uses `mlx.core` / `mlx.nn`; keep MLX imports lazy at the package root and CLI. Float32 reductions where needed, float16 optional weights, bounded input lengths. No global model cache.
+- Preserve checkpoint-compatible parameter names and provide explicit tensor-layout conversion rules. Loading must be strict; never silently skip mismatched keys.
+- Tests use tiny configurations and bounded inputs, never network access. Report what has actually been verified; architecture tests are not real-checkpoint acceptance.
+- Temporary artifacts belong in `.tmp/`. Do not write to `/tmp`.
+- Scope edits to assigned files, commit changes, and report commit SHA and remaining gaps.
+- Use `read`/`grep`/`find` for retrieval and `edit`/`write` for manual changes.

funasr_mlx-0.1.0/LICENSE

@@ -0,0 +1,26 @@
+MIT License
+
+Copyright (c) 2026 funasr-mlx contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+The Software contains derivative works vendored from mlx-lm
+(https://github.com/ml-explore/mlx-lm), Copyright (c) 2023-2024 Apple Inc.,
+licensed under the Apache License, Version 2.0; see the module docstrings in
+src/funasr_mlx/models/llm/ for scope.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

funasr_mlx-0.1.0/OPTIMIZATION.md

@@ -0,0 +1,154 @@
+# Optimization Backlog — 17 Items by Distance-to-Roofline
+
+**Date:** 2026-10-04 · **Host:** MacBook Air M4 (16 GB) · **Batch size:** 1 everywhere
+
+> **Post-mortem addendum (2026-10-04, whisper sprint).** Two items below were
+> closed as MEASURED-AND-REJECTED, and the lead's original attribution for both
+> was wrong twice. Recorded so the same traps are not re-run:
+>
+> 1. **Encoder elementwise fusion (#13 tiny / large enc rows)**: NOT real. The
+>    1.65x came from (a) a timing-protocol artifact — `for KK: r=fn()` + one
+>    `mx.eval(r)` evaluates only the last lazy graph (wall time FLAT in KK while
+>    "per-iter" falls 1/KK; real slice cost ~3.0-3.4 ms, not 210 us), and (b) a
+>    hand-rolled 3-kernel GELU, while the model uses fused `mxnn.GELU()`.
+>    Honest paired A/B: tiny -1.3% p=0.29, large-v3 -0.06% p=0.90. Encoder is
+>    already at 73% of machine fp16 peak and FASTER than the sum of its parts.
+>    The 13-15 ms target was below the hardware floor (36.7 GFLOP / 2.44 TFLOPS
+>    = 15.0 ms). Evidence: reports/whisper-encoder-fusion.md.
+> 2. **Decode KV-append replacement (whisper decode rows)**: NOT worth it. The
+>    "52% of layer" claim was a sum-of-parts fallacy (isolated concat 0.17-0.30
+>    ms summed into block attribution; inside a real block the append is ~0.1 ms
+>    of ~1.1 ms). A numerically exact prealloc/slice-assign buffer was built and
+>    reverted: 300-pair A/B -0.6%, CI95 [-0.158,+0.087], p=0.603. Ceiling for ANY
+>    append mechanism: 0.116/0.079 ms (10%/7% of block); slice-assign captured
+>    negative. Remaining decode cost is per-op dispatch count + the lm_head
+>    bandwidth floor — no cache representation removes it.
+>    Evidence: reports/task-3-*.md.
+>
+> **Methodology rules that fell out** (apply to every future probe):
+> - eval INSIDE the timed region, every iteration; never rebind-and-drop.
+> - Probe with the model's REAL ops (`mxnn.GELU`), never hand-rolled stand-ins.
+> - Never sum isolated op costs into a stage attribution — inter-op overlap
+>   hides/shows costs (real chain beat parts-sum in both directions here).
+> - Paired in-process A/B is the only valid comparison; absolutes drift with
+>   thermal (observed: same probe 4.73 vs 5.97 ms across sessions).
+> - A 2.5%/p=0.055 result that fails to replicate at n=300 is noise; demand
+>   >=5% with CI excluding zero before shipping.
+
+## Measurement basis
+
+- **Ceilings are measured on this machine, not spec numbers**
+  (`.tmp/probe_hardware.py`, best-of-10):
+  - fp16 GEMM **2.58 TFLOPS** @ 4096³ (2.30 @ 8192³)
+  - fp32 GEMM **2.27 TFLOPS** → fp16 has only a **1.14×** compute edge on this host
+  - DRAM bandwidth **92 GB/s**
+  - Ridge point ≈ 28 FLOP/byte: decode (intensity ~1.3) is memory-bound → judge
+    by **MBU**; towers/prefill are compute-bound → judge by **MFU**.
+- Latency: `tools/benchmark_speed.py` + `.tmp/bench_fp16_llm.py` /
+  `.tmp/bench_fp16_small.py`, current post-SDPA code, warmup + 20-30 repeats.
+- FLOPs/bytes are analytic (2·params·tokens + attention T² terms; weights read
+  once per call), not kernel-traced — the *gap*, not the percentage, is the signal.
+- Full tables: `.tmp/ceiling_analysis.json`, `.tmp/ceiling_analysis_small.json`.
+
+## The 17 items, worst gap first
+
+| # | Model | Stage | dtype | t (ms) | MFU% | MBU% | **Gap** | Bound | RTF context (fp16) |
+|---|-------|-------|-------|--------|------|------|---------|-------|---------------------|
+| 1 | fsmn-vad | forward | fp16 | 3.4 | 3.2 | 0.6 | **31.2×** | launch latency | 0.0010 (968×) |
+| 2 | whisper-tiny | decode/step | fp16 | 5.2 | 0.3 | 7.2 | **13.9×** | bandwidth | 3.0 ms/step effective |
+| 3 | moss | adaptor | fp16 | 2.0 | 10.7 | 5.7 | **9.4×** | mixed | (tower unmeasured, see #17) |
+| 4 | campplus | forward | fp16 | 15.0 | 11.7 | 1.1 | **8.5×** | launch latency | 0.0046 (219×) |
+| 5 | glm-asr-nano | decode/step | fp16 | 244.4 | 0.5 | 14.2 | **7.1×** | bandwidth | RTF 1.53 — not realtime |
+| 6 | glm-asr-nano | prefill | fp16 | 306.0 | 15.0 | 11.4 | **6.7×** | compute | ↑ |
+| 7 | qwen3-asr-0.6b | decode/step | fp16 | 98.9 | 0.6 | 16.5 | **6.1×** | bandwidth | RTF 0.605 (1.7×) |
+| 8 | whisper-tiny | decode/step | fp32 | 4.0 | 0.4 | 18.7 | **5.3×** | bandwidth | fp32 faster than fp16 |
+| 9 | emotion2vec | forward | fp16 | 60.3 | 23.7 | 6.0 | **4.2×** | compute | — |
+| 10 | qwen3-asr-0.6b | prefill | fp16 | 127.0 | 30.5 | 13.0 | **3.3×** | compute | ↑ #7 |
+| 11 | glm-asr-nano | tower | fp16 | 243.0 | 41.8 | 5.7 | **2.4×** | compute | ↑ #5 |
+| 12 | moss | prefill | fp16 | 101.0 | 42.4 | 13.1 | **2.4×** | compute | RTF 0.132 (7.6×) |
+| 13 | sensevoice | enc+ctc | fp16 | 42.5 | 35.4 | 12.5 | **2.8×** | compute | fp32 is 28.8 ms |
+| 14 | paraformer | enc+dec | fp16 | 43.2 | 37.8 | 11.7 | **2.6×** | compute | fp32 is 27.8 ms |
+| 15 | emotion2vec | forward | fp32 | 47.1 | 30.4 | 7.7 | **3.3×** | compute | fp32 faster |
+| 16 | qwen3-asr-0.6b | tower | fp16 | 41.0 | 77.1 | 9.9 | **1.3×** | compute | near ceiling ✅ |
+| 17 | fun-asr-nano | decode+prefill | fp16 | 16.7/31.0 | 3.5 | **98.0** | **1.0×** | bandwidth | AT the roofline ✅ |
+
+*(whisper-tiny encoder 1.6×, sensevoice/paraformer fp32 1.7-1.9×, ct-punc 1.5×
+are already within 2× of their roofs and are not listed as work items.)*
+
+## Grouped by fix, highest leverage first
+
+### A. LLM decode path — fixes #5, #7 (and lifts #2's relatives)
+**The single biggest win.** fun-asr-nano's decode runs at **98% of memory
+bandwidth** (1.0×, item #17) on a **Qwen3-0.6B backbone with the identical
+751.6 M params and identical 1.50 GB/step weight traffic as qwen3-asr**, yet
+qwen3-asr takes 98.9 ms/step vs nano's 16.7 ms — a **6× gap that is pure call
+path, not model size**.
+- Suspect 1: `KVCache.update_and_fetch` does `self.keys[:, :, offset:n] = k`
+  slice-assign per step; if not in-place this rewrites the whole buffer
+  (28 layers × K/V × every step).
+- Suspect 2: `.item()` / `mx.argmax(...).item()` forces a sync every token.
+- Payoff if brought to nano's efficiency: qwen3-asr RTF 0.605 → ~0.35;
+  glm-asr-nano decode 244 → ~40 ms/step, RTF 1.53 → ~0.85 (**crosses into
+  realtime**). Verify with `mx.metal.set_wire_per_frame`-style profiling or by
+  timing a bare `model(x, cache=...)` loop.
+
+### B. Drop fp16 for mixed-dtype models — fixes #2, #8, #13, #14, #15
+On this host fp16 GEMM is only 1.14× fp32, so fp16 **cannot** pay for its
+mixed-dtype promotion. Measured regressions vs native precision:
+sensevoice −48%, paraformer −55%, emotion2vec −28%, whisper-tiny e2e −43%,
+glm decode −18%, qwen3 decode −10%, moss −8%.
+**Action:** default these families to fp32 (or bf16) weights; keep fp16 only
+where bandwidth-bound (ct-punc: **+28% faster**, the sole winner, because its
+971 MB embedding read halves).
+Also note SDPA fusion is a **net negative under fp16** here: sensevoice −13%,
+paraformer −24%, emotion2vec −11% vs the pre-SDPA fp16 numbers, while it helped
+fp32 (−8%/−2%). Gate SDPA on dtype.
+
+### C. Launch-latency-bound small models — #1, #3, #4
+fsmn-vad (3.2% MFU, 31×) and campplus (11.7%, 8.5×) are far from any roof, but
+their absolute cost (3.4 / 15 ms) is already 219-968× realtime — **the gap is
+real yet the payoff is nil unless used in a tight loop** (streaming VAD at
+100 fps × chunks). If ever needed: fuse the 24-70 sequential small GEMMs
+(`mx.compile` measured +0.8% = noise; needs graph-level batching instead).
+fsmn-vad's whole forward is smaller than one Metal dispatch batch.
+
+### D. Remaining compute-bound stages — #6, #9, #10, #11, #12
+All transformer forwards at 15-42% MFU. Causes are the documented M4 envelope
+(sequential 560-1024-dim GEMMs below the compute-bound threshold) plus, for
+GLM tower (#11), attention over T=201 with d=1280. Expected recoverable headroom
+is ~2× at best; these are genuine hardware limits, not bugs — deprioritize
+behind A and B.
+
+### E. Measurement debt — #3 (moss tower), caveat on #5/#7
+- MOSS's whisper encoder ran **outside the timed region** on a padded 30 s
+  window; only the 2 ms adaptor was timed. Its published RTF 0.132 is therefore
+  **optimistic**. Re-bench with the encoder inside.
+- GLM prefill/decode were measured with `lowest_available` down to 1.76 GB
+  (below the 3 GB reserve; policy is advisory there) — numbers are valid but
+  were collected under memory pressure.
+- ct-punc fp32 needs `process_limit ≥ 4 GB` (971 MB largest tensor vs
+  `process_limit/4` admission); first-ever fp32 run of that family.
+
+## Non-items (already at/near the roof)
+
+fun-asr-nano decode **1.0×** (98% MBU), its prefill 1.2× (84% MFU), qwen3 tower
+1.3× (77%), whisper-tiny encoder 1.6× (61%), ct-punc fp16 1.5× (69% MBU).
+**No optimization is possible on these without different hardware.**
+
+## Reproduction
+
+```sh
+# ceilings
+PYTHONPATH=src python3 -m funasr_mlx.runtime --root . --report .tmp/ph.json -- \
+  python3 .tmp/probe_hardware.py
+# small families (fsmn-vad/campplus/whisper-tiny)
+PYTHONPATH=src python3 -m funasr_mlx.runtime --root . --report .tmp/b.json -- \
+  python3 .tmp/bench_fp16_small.py --dtype float16 --repeats 20 --warmup 3 \
+  --out /Volumes/2T/funasr-mlx-alignment/results/bench-small-float16.json
+# sensevoice/paraformer/emotion2vec/ct-punc (ct-punc fp32 needs ≥4GB process_limit)
+python3 .tmp/run_small2.py
+# LLM families (serialized)
+python3 .tmp/run_bench_matrix.py
+# this table
+python3 .tmp/ceiling_analysis.py && python3 .tmp/ceiling_analysis_small.py
+```

funasr_mlx-0.1.0/PKG-INFO

@@ -0,0 +1,255 @@
+Metadata-Version: 2.5
+Name: funasr-mlx
+Version: 0.1.0
+Summary: Native MLX speech inference (SenseVoice, Paraformer, Whisper, Qwen3-ASR, GLM, MoSS, Fun-ASR-Nano) with W4A16 quantization, an OpenAI-compatible server and pseudo-streaming, for Apple Silicon
+Author: baicai1145
+License: Apache-2.0
+License-File: LICENSE
+Keywords: apple-silicon,asr,funasr,mlx,qwen3,sensevoice,speech-recognition,whisper
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Requires-Dist: mlx>=0.32.0
+Requires-Dist: numpy>=1.26
+Requires-Dist: psutil>=5.9
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: safetensors>=0.4
+Requires-Dist: soundfile>=0.12
+Provides-Extra: convert
+Requires-Dist: huggingface-hub>=0.24; extra == 'convert'
+Requires-Dist: torch>=2.2; extra == 'convert'
+Provides-Extra: reference
+Requires-Dist: librosa>=0.10; extra == 'reference'
+Requires-Dist: torch>=2.2; extra == 'reference'
+Requires-Dist: torchaudio>=2.2; extra == 'reference'
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# funasr-mlx
+
+Native [MLX](https://github.com/ml-explore/mlx) inference ports of the
+FunASR model zoo for Apple Silicon — memory-bounded, numerically verified
+against the official references, with no PyTorch/runtime dependency at
+inference time.
+
+All 14 checkpoints covering 11 architectures from the FunASR README model
+zoo are ported. Every port is validated layer-by-layer against its
+official implementation (fp32, shared-input parity) and end-to-end on real
+audio before it is marked done.
+
+## Coverage & Verification
+
+| Model | Family | Layer parity (fp32) | Real-audio e2e |
+| --- | --- | --- | --- |
+| SenseVoiceSmall | `sensevoice` | source-exact diffs | ✅ |
+| Paraformer (offline) | `paraformer` | rel 1e-6 (GEMM noise) | ✅ CER ~0 |
+| Paraformer streaming | `paraformer` | 4.0e-7 tail path | ⚠️ CER 0.156* |
+| Whisper tiny | `whisper` | canonical full-forward | ✅ |
+| Whisper large-v3 | `whisper` | enc 1.5e-4 / dec 2.3e-5 | ✅ RTF 0.058 |
+| Whisper large-v3-turbo | `whisper` | enc 5.3e-4 / dec 2.6e-4 | ✅ RTF 0.061 |
+| emotion2vec+large | `emotion2vec` | fairseq-exact CNN/pos | ✅ |
+| ct-punc | `ct-punc` | conv-tap exact | ✅ |
+| fsmn-vad | `fsmn-vad` | conv/cache exact | ✅ |
+| CAM++ | `campplus` | source-exact | ✅ |
+| Fun-ASR-Nano | llm | audio 4.6e-3 / LLM 3.0e-6 | ✅ 8/8 |
+| Qwen3-ASR-0.6B | llm | audio 1.2e-5 / dec 1.4e-4 | ✅ 6/6 |
+| GLM-ASR-Nano-2512 | llm | tower 2.0e-5 / llama 3.3e-6 | ✅ 7/7 |
+| MOSS-Transcribe-Diarize | llm | enc 1.3e-3 / dec 4.7e-5 | ✅ 8/8 +timestamps+speakers |
+
+\* Streaming Paraformer: single-layer diffs are 1e-6, but the chunked
+streaming state machine amplifies fp32 noise until CIF fire positions
+drift (MLX has no fp64). Use streaming for partial results and the
+offline model for final transcripts.
+
+The four LLM-based models (Fun-ASR-Nano, Qwen3-ASR, GLM-ASR-Nano,
+MOSS-Transcribe-Diarize) are ported and numerically verified
+(`src/funasr_mlx/models/` + `models/llm/`), with e2e validated through
+bf16 scripts; their pipeline-factory registration is pending. The seven
+speech families above run through the guarded CLI today.
+
+## Local Use
+
+Install on an Apple Silicon Mac with Python 3.11+:
+
+```sh
+python3 -m pip install -e .
+funasr-mlx --help
+```
+
+Inspect a local checkpoint or extract bounded features:
+
+```sh
+funasr-mlx inspect /path/to/model.safetensors
+funasr-mlx features recording.wav --cmvn none
+```
+
+Inference requires a local converted checkpoint directory and a matching
+native JSON or YAML configuration:
+
+```sh
+funasr-mlx infer /path/to/checkpoint-dir --model sensevoice --audio recording.wav
+funasr-mlx infer /path/to/checkpoint-dir --model ct-punc --text "hello world" --tokens /path/to/tokens.txt
+```
+
+## W4A16 quantization
+
+4-bit weights with 16-bit activations for the LLM-ASR decoders, using MLX
+affine group quantization (group size 64). At batch size 1 the decode step
+streams the weights once per step, so reading 4x fewer bytes is the largest
+remaining lever; measured on an M4 it cuts peak inference memory 41-59% and
+decode time up to 2.7x across the five families.
+
+Convert a native checkpoint, then load it exactly as an unquantized one:
+
+```sh
+python3 tools/convert_llm_checkpoints.py --family qwen3-asr-0.6b \
+    --source /path/to/qwen3-asr-0.6b --destination /path/to/qwen3-asr-0.6b-w4a16 \
+    --native-source --quantize tower
+```
+
+`--quantize` picks how much is quantized, and the choice is not cosmetic:
+
+| scope | reaches | buys |
+|---|---|---|
+| `decoder` | decoder Linear layers | decode time |
+| `tower` | + the audio tower | peak memory; the tower runs once per utterance, so no decode cost |
+| `all` | + the tied token embedding | removes the per-step LM-head read, but only some families survive it |
+
+The token embedding is the tied LM head, so quantizing it injects 4-bit error
+directly into every step's logits. It is safe for `fun-asr-nano` (tokens fully
+identical) and destroys the transcript for `qwen3-asr-0.6b` and `glm-asr-nano`,
+so `all` is opt-in per family rather than a default. `lm_head`, position tables,
+convolutions and norms are never quantized. Loading is strict: the config
+records `quantized_tensors` and `quantization_skipped`, and a key that should
+have been quantized but was not is an error, not a silent fallback.
+
+Per-family scope, checkpoint sizes, measured speedups and peak-memory drops are
+in `.tmp/t9/RESULTS.md`; the scheme and its failure modes are in
+`.tmp/t9/LEDGER.md`.
+
+## Downloading published checkpoints
+
+No hub dependencies (stdlib HTTPS only; HF and MS mirrors with per-file
+fallback; ~5-6 MB/s ceiling is the hosts' per-IP throttle, not client):
+
+```sh
+funasr-mlx download qwen3-asr-0.6b-mlx --variant w4a16 --dest ./models
+# classic models omit --variant:
+funasr-mlx download sensevoice-mlx-fp16 --dest ./models
+```
+
+Then transcribe directly from the download:
+
+```sh
+funasr-mlx transcribe ./models/qwen3-asr-0.6b-mlx/w4a16 --audio recording.wav
+```
+
+## LLM-ASR transcription
+
+Three interfaces share one resident-worker protocol (KV cache reset-reuse
+between requests; RTF 0.079 on the 0.6B w4, M4 Air):
+
+CLI (single file):
+
+```sh
+funasr-mlx transcribe /path/to/qwen3-asr-0.6b-w4a16-awq-w8tower-g32 --audio recording.wav
+# {"text": "...", "token_ids": [...], "family": "qwen3-asr", "wall_ms": 650.8}
+```
+
+Python API (routes through the guarded subprocess automatically):
+
+```python
+from funasr_mlx.api import transcribe, download_model
+path = download_model("qwen3-asr-0.6b-mlx", variant="w4a16", dest="./models")
+result = transcribe("recording.wav", model=path / "w4a16")
+print(result["text"])
+```
+
+HTTP server (OpenAI-compatible endpoint; raw body or multipart form):
+
+```sh
+funasr-mlx serve /path/to/checkpoint --port 8000
+curl -X POST http://127.0.0.1:8000/v1/audio/transcriptions -F "file=@recording.wav"
+```
+
+Supported families: `qwen3-asr` (0.6B/1.7B), `glm-asr-nano`,
+`moss-transcribe-diarize`, `fun-asr-nano` (family inferred from the
+checkpoint directory name when omitted).
+
+## Pseudo-streaming (all transcription families)
+
+`funasr_mlx.pseudo_streaming.PseudoStream` gives every transcription model
+a streaming-style API over a growing audio buffer: each `push()` re-runs the
+model on `buffer[0:t]`, `close()` returns output bit-identical to offline
+(measured: 94.6% of displayed characters survive to final; revisions are
+confined to the rolling tail, .tmp/opt/LOG.md).
+
+- LLM families (`qwen3-asr`, `glm-asr-nano`, `moss`, `fun-asr-nano`):
+  `TranscribeWorker.pseudo_stream()`; tower+prefill recompute per push
+  (~150-800ms per 1s chunk on the 0.6B w4).
+- Classic families (`sensevoice`, `paraformer`): single-pass per push;
+  `classic_transcriber(model, config, family=..., tokens=..., cmvn=...)`
+  (cmvn REQUIRED for sensevoice -- without `am.mvn` the encoder collapses
+  to all blanks).
+
+```python
+from funasr_mlx.api import TranscribeWorker
+worker = TranscribeWorker("models/qwen3-asr-0.6b-mlx/w4a16")
+stream = worker.pseudo_stream(chunk_seconds=1.0)
+for chunk in mic:                 # numpy float32 @16k, any sizes
+    ev = stream.push(chunk)
+    if ev: render(ev.text)        # stable prefix + rolling tail
+final = stream.close()            # == offline transcription
+```
+
+## Memory guard (optional, dev-machine tool)
+
+`funasr_mlx.memory.run_guarded` is a host-protection wrapper developed on a
+16GB MacBook Air: it bounds per-process RSS and wired-memory headroom while
+big checkpoints load. It is NOT a project requirement:
+
+* Library callers (`funasr_mlx.api`, `pipeline.load_model`) load and run
+  in-process by default, with no guard and no policy environment.
+* `funasr-mlx` CLI still wraps execution in the guard by default
+  (`--memory-gb`), convenient for constrained machines; set
+  `FUNASR_MLX_MEMORY_POLICY=""` handling per platform if you want to bypass.
+* Budget checks (weights-vs-limit, shard caps) apply only when a policy is
+  present in the environment.
+
+
+## Development
+
+Optional `test`, `reference` and `convert` dependency groups. Source
+differential tests use a sibling FunASR checkout; unavailable references
+skip. Guarded verification:
+
+```sh
+PYTHONPATH=src PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 python3 -m funasr_mlx.runtime \
+  --root . --report .tmp/check.json -- \
+  python3 -m pytest -q --tb=short --basetemp=.tmp/pytest-check
+```
+
+503 tests pass in the guarded suite. Real-checkpoint accuracy, quantized
+variants, and latency/RTF figures are documented in `PROGRESS.md`; the W4A16
+per-family numbers are in `.tmp/t9/RESULTS.md`.
+
+## Attribution
+
+Qwen3/Llama decoder layouts and the KV cache are vendored (trimmed) from
+[mlx-lm](https://github.com/ml-explore/mlx-lm) (Apache 2.0, Copyright ©
+2023-2024 Apple Inc.); source and license notes are in the module
+docstrings. Model architectures follow their official references
+(FunASR, OpenAI Whisper, Qwen, GLM, OpenMOSS).
+
+## Status
+
+Experimental: numerically verified ports, not a production service. No
+fastest / lowest-memory / production-quality claim is made.