Clarify required runtime and add download diagnostics

Document the reproduced unpatched-loader failure, add a bounded-memory download and runtime checker, and explain how to obtain the original generation-worker error. Preserve all weights and architecture patches. Full-model Mac execution and the reported third-party failure remain unverified.

README.md

@@ -32,6 +32,17 @@ reasoning-efficient Qwen3.8-27B derivative, focused on long-horizon, agentic and
 coding tasks. This export preserves the text, vision and MTP parameter tree;
 its supported generation interface is text-only with the included MLX-LM patches.
 
+**Runtime compatibility:** this complete checkpoint requires both supplied patches, in the order shown
+and the pinned Python installation in [USAGE.md](USAGE.md). The tested unpatched
+MLX-LM 0.32.0 loader rejects 501 saved vision entries. Downloading the model does
+not install these patches into an app's inference engine. GUI compatibility and
+full 27B Apple Silicon generation remain unverified.
+
+The complete weights total **19.28 GB (17.96 GiB) across 4 required shards**, plus
+config, index and tokenizer files. A single 5–6 GB file is not the complete model.
+For download checks or `404 generation thread died`, use
+[TROUBLESHOOTING.md](TROUBLESHOOTING.md).
+
 Swift 1.5 uses **58.5% fewer thinking tokens** than base Qwen3.8-27B while scoring **0.35% higher**, for a **9.18× speed-up** on several tasks.
 
 > [!CAUTION]
@@ -40,6 +51,19 @@ Swift 1.5 uses **58.5% fewer thinking tokens** than base Qwen3.8-27B while scori
 > Full independent Apple Silicon generation and quality evaluation remain **NOT_RUN**.
 > The 19.28 GB tensor payload must not be forced onto a 16 GiB Mac.
 
+## Download the complete model
+
+This repository is public; authentication is optional. Use a complete download:
+
+```bash
+hf download ukisai/Swift-1.5-5bit-MLX --local-dir Swift-1.5-5bit-MLX
+python Swift-1.5-5bit-MLX/check_download.py Swift-1.5-5bit-MLX --hash
+```
+
+All four `model-0000*-of-00004.safetensors` files are required. Follow [USAGE.md](USAGE.md)
+to install both runtime patches before attempting generation. A download check
+does not establish successful inference or sufficient RAM.
+
 ## Demo
 
 We gave base Qwen3.8-27B and Swift 1.5 27B the same prompt:

TROUBLESHOOTING.md

@@ -0,0 +1,79 @@
+# Check this download and its runtime
+
+This release needs **all 4 shards (19.28 GB (17.96 GiB))**, its index/config/tokenizer
+assets, and both supplied patches, in the order shown. Downloading an HF repository does not install
+the MLX-LM patches into Python or into a GUI app's separate runtime.
+
+## 1. Verify the files without loading the model
+
+Run from the directory containing `Swift-1.5-5bit-MLX`:
+
+```bash
+python Swift-1.5-5bit-MLX/check_download.py Swift-1.5-5bit-MLX --hash
+```
+
+This uses standard Python, reads the headers and stream-checks the original shard
+SHA-256 hashes with bounded memory. It does not load the model or contact a server.
+A successful result verifies the listed download checks, not inference.
+
+If files are missing or incomplete, resume the full download using the pinned
+snapshot instructions in [USAGE.md](USAGE.md), then verify again. Keep all shards
+in one directory alongside the index, config and tokenizer. Do not load a single
+shard or a diagnostic sample as a standalone model. Do not combine 4-bit and 5-bit
+files. The complete 4-bit payload is 15.83 GB; the complete 5-bit payload is 19.28 GB.
+A reported 5.7 GB download is insufficient for either complete checkpoint, although
+that number alone does not tell us what an app has downloaded or is displaying.
+
+## 2. Verify the runtime
+
+Follow [USAGE.md](USAGE.md) to install both supplied patches, in the order shown in the pinned Python
+environment. Then, in that same environment:
+
+```bash
+python Swift-1.5-5bit-MLX/check_download.py Swift-1.5-5bit-MLX --runtime
+```
+
+The checker confirms that MLX-LM dispatches to `qwen3_5_full` and that its architecture
+source matches the audited supplied patch. It records the MLX and MLX-LM versions.
+It deliberately rejects other architecture code until checked separately.
+For 5-bit, the base architecture patch alone is insufficient: `enable-5bit.patch`
+must also be applied. A passing check in a terminal does not change an app's
+separate runtime. GUI integration has not been validated for these full checkpoints.
+
+Do not remove vision/MTP parameters or change the config to force a stock text
+loader to accept the file. All 2,379 saved tensor entries belong to this release.
+
+## 3. If a server reports `404 generation thread died`
+
+In the pinned official MLX-LM server, this message means its generation worker
+failed. The HTTP 404 is not enough to diagnose a missing web page, a broken model,
+or a plugin problem. The original exception is in the server's terminal/log, before
+the later generic response.
+
+After the file and runtime checks pass, run the short direct Python generation
+example in [USAGE.md](USAGE.md) in the same environment, independently of any plugin.
+Use a Mac with sufficient RAM for the complete weights, runtime, cache and macOS.
+Full-model generation on a 24 GB Mac has not been verified. Neither full release
+has been validated on the available 16 GiB test Mac; do not raise memory limits.
+
+If it fails, retain the original exception and traceback. A useful report contains
+the app/command and version, Mac RAM, model revision, checker output, and that first
+exception. Do not include access tokens or private prompts. Repeating a request
+against a dead worker will not recover it; restart only after addressing the cause.
+
+## What was checked on 2026-09-25
+
+- Both public releases contain all indexed shards and 2,379 matching tensor headers.
+- The unpatched official MLX-LM 0.32.0 model at the revision pinned in USAGE rejects
+  501 saved vision entries and removes 31 saved MTP entries during sanitization.
+  The required patched parameter trees accept all 2,379 entries with no shape mismatch.
+  These comparisons use real headers and unevaluated zero fixtures, not full payloads.
+- An incomplete checkpoint reproduced the exact HTTP 404 / `generation thread died`
+  response. That demonstrates one possible cause, not the cause of any specific report.
+- Both patched 4-bit and 5-bit runtimes passed small synthetic HTTP tests for
+  non-thinking chat, default thinking format, seeded generation, and streaming with
+  a tool definition. These are architecture/server checks, not full Swift generation
+  or a test of the reported third-party plugin.
+
+The reporter's original traceback is still needed to identify their specific failure.
+These checks do not establish full-model Mac execution or GUI compatibility.

UPLOAD_MANIFEST.json

@@ -32,15 +32,21 @@
     },
     {
       "path": "README.md",
-      "bytes": 6283,
-      "sha256": "77bebdc893764e1ddb8499b4dd614856a33a39689ca03c46623c11f7a6480722",
-      "git_blob_sha1": "91d0f0da8a67b2a793ccb1fc16e54d6e14b67729"
+      "bytes": 8067,
+      "sha256": "e0ce3327646a3dde90ee001a3bb819c8cb24e550a83d28340671f2542e7ad55b",
+      "git_blob_sha1": "008e4ab150bc188e372cad12fda89317afda850e"
+    },
+    {
+      "path": "TROUBLESHOOTING.md",
+      "bytes": 4380,
+      "sha256": "32b67c70616257a0e26e91bbc6b1b880391872f98c4292aece9488940cda9d00",
+      "git_blob_sha1": "2968859f3f32fc644fc20c2fb9e9644e10535e43"
     },
     {
       "path": "USAGE.md",
-      "bytes": 4963,
-      "sha256": "8d9aeb9c1a86a8e23bc4daf4c7b38b3f8af7a7e0b8b74616e411346469b3cc0e",
-      "git_blob_sha1": "816e5c09652657535d15d4d8fddfb59b2253cd43"
+      "bytes": 5431,
+      "sha256": "be75f4abc1868a29866013d9fd6490644f6c06cf3effe6e2704f3e6657affddb",
+      "git_blob_sha1": "db137784896c403a7ee030bb56f335503227baf6"
     },
     {
       "path": "chat_template.jinja",
@@ -48,6 +54,12 @@
       "sha256": "c3cf9e34abf4f9e36c2d72165aa9c132d3e2a725b6c2586aaa3a8af9d7a81041",
       "git_blob_sha1": "c0c686f9c38d70d179fb7b5f5aa7530bc913dda3"
     },
+    {
+      "path": "check_download.py",
+      "bytes": 9658,
+      "sha256": "1e424a32bb015431df22b8f058aa18de116ae63e0440d60424792a1cf2fd4018",
+      "git_blob_sha1": "57c4bddd7813e480c7a738ea997e2bb4e3cc51ff"
+    },
     {
       "path": "compatibility/LICENSE-MLX-LM-MIT",
       "bytes": 1066,
@@ -204,7 +216,7 @@
       "git_blob_sha1": "0aa0ce0658d60ac4a5d609f4eadb0e8e43514176"
     }
   ],
-  "file_count": 35,
-  "total_bytes": 19310861234,
+  "file_count": 37,
+  "total_bytes": 19310877524,
   "self_excluded": true
 }

USAGE.md

@@ -7,8 +7,7 @@ or raise system memory limits to conceal insufficient hardware.
 
 ## Pin the snapshot and verify it
 
-Use a new working directory. After installing the HF CLI, run `hf auth login`
-interactively if not already signed in with access to this private repository.
+Use a new working directory. This repository is public; authentication is optional.
 The command below resolves current main once to a full commit and then uses
 only that pinned snapshot. For a repeat run, reuse the recorded commit.
 Do not use an incomplete historical upload or proceed after verification failure.
@@ -21,6 +20,7 @@ SWIFT_MLX_REVISION="$(python -c 'from huggingface_hub import HfApi; print(HfApi(
 printf 'Pinned model revision: %s\n' "$SWIFT_MLX_REVISION"
 hf download ukisai/Swift-1.5-5bit-MLX --revision "$SWIFT_MLX_REVISION" --local-dir Swift-1.5-5bit-MLX
 hf cache verify ukisai/Swift-1.5-5bit-MLX --revision "$SWIFT_MLX_REVISION" --local-dir Swift-1.5-5bit-MLX --fail-on-missing-files
+python Swift-1.5-5bit-MLX/check_download.py Swift-1.5-5bit-MLX
 python Swift-1.5-5bit-MLX/verify_release.py Swift-1.5-5bit-MLX
 ```
 
@@ -60,6 +60,17 @@ audit, where 18 synthetic patch tests passed. These environments are not identic
 and the tests did not load the full 27B model. The upstream code
 [MIT notice](compatibility/LICENSE-MLX-LM-MIT) is included separately from weight licenses.
 
+Before generating, check the Python environment that will actually run the model:
+
+```bash
+python Swift-1.5-5bit-MLX/check_download.py Swift-1.5-5bit-MLX --runtime
+```
+
+This checks the complete download and selects the pinned patched architecture
+without loading weights. It does not check a separate GUI app's environment,
+available inference memory, or generated quality. See [TROUBLESHOOTING.md](TROUBLESHOOTING.md)
+if it fails or a server reports `generation thread died`.
+
 ## Text generation
 
 ```python

check_download.py

@@ -0,0 +1,188 @@
+#!/usr/bin/env python3
+"""Check a Swift 1.5 4/5-bit download and optional pinned Python runtime.
+
+Does not download files, load weights, generate text, or certify GUI compatibility.
+"""
+import argparse
+import hashlib
+import json
+from pathlib import Path
+import struct
+import sys
+
+RELEASES = {4: {
+    'model-00001-of-00003.safetensors': (5328325554, 'd91b70ca84dff315addeeb8a599dce2beccfec33c7483686ede2e8ff3cc459dc'),
+    'model-00002-of-00003.safetensors': (5354185158, 'eddcff1a6ef0971990f7cd01dba77ab9a8c20d59821bb4cd7e25234fe3809346'),
+    'model-00003-of-00003.safetensors': (5144253923, '644cc5322ff706c9608b42ea1ff83e0beb12b828d49b36c468a366f44593b8eb'),
+}, 5: {
+    'model-00001-of-00004.safetensors': (5360417859, '9da8750595ec42d8c5d2ff0ae0b695e387cbcb3c0beac40f262e6d9a7196b59d'),
+    'model-00002-of-00004.safetensors': (5338181777, 'b592723bd4e9f01344335cd7d4b4f41a7c8cde98e2e074ad1d943cdb951a6835'),
+    'model-00003-of-00004.safetensors': (5355925620, '0027e7fe05310d5b2d960414221ed0872de9b511aa7e6b1c3a8f0e4647558412'),
+    'model-00004-of-00004.safetensors': (3227578201, 'afec577f16805b327471561d6841662eb4acf7d866ad5e761c5ef8cd3149d8f4'),
+}}
+EXPECTED_TENSORS = 2379
+MODEL_HASHES = {
+    4: {'f559e4559946bfad4ce20b93906028449b76e007f42f36bb83d2c2c5f6cb95a9',
+        'ecda666d6d5f1059388a2ce4267d9ff8625398bb925d6c0840d0059ce17b676f'},
+    5: {'ecda666d6d5f1059388a2ce4267d9ff8625398bb925d6c0840d0059ce17b676f'},
+}
+REQUIRED = (
+    'config.json', 'model.safetensors.index.json', 'tokenizer.json',
+    'tokenizer_config.json', 'chat_template.jinja', 'generation_config.json',
+    'vocab.json', 'merges.txt', 'preprocessor_config.json', 'video_preprocessor_config.json',
+)
+
+def unique(pairs):
+    result = {}
+    for key, value in pairs:
+        if key in result:
+            raise ValueError('Duplicate JSON key')
+        result[key] = value
+    return result
+
+def read_json(path):
+    return json.loads(path.read_text(encoding='utf-8'), object_pairs_hook=unique)
+
+def runtime_check(config):
+    """Check dispatch and the audited architecture source, without model creation."""
+    import inspect
+    from importlib.metadata import version
+    from mlx_lm.utils import _get_classes
+    cls, args = _get_classes(config)
+    args.from_dict(config)
+    row = {'mlx': version('mlx'), 'mlx_lm': version('mlx-lm'),
+           'selected_model_class': cls.__module__+'.'+cls.__name__}
+    if cls.__module__ != 'mlx_lm.models.qwen3_5_full':
+        raise ValueError('The required full-model MLX-LM patch is not active. Follow USAGE.md in this Python environment.')
+    row['model_source_sha256'] = hashlib.sha256(Path(inspect.getsourcefile(cls)).read_bytes()).hexdigest()
+    if row['model_source_sha256'] not in MODEL_HASHES[config['quantization']['bits']]:
+        raise ValueError('This is not the pinned patched model implementation. For 5-bit, both patches are required. Follow USAGE.md.')
+    return row
+
+def check(folder, check_hashes=False, check_runtime=False):
+    folder = Path(folder)
+    errors = []
+    report = {'files':[], 'weights_loaded':False, 'generation_tested':False,
+              'scope':'File sizes, headers, index and requested checks only; no full-model or GUI test'}
+    try:
+        config = read_json(folder/'config.json')
+        bits = config['quantization']['bits']
+        if type(bits) is not int or bits not in RELEASES:
+            raise ValueError('Expected 4-bit or 5-bit Swift release')
+        expected = RELEASES[bits]
+    except (OSError,ValueError,KeyError,TypeError) as exc:
+        return dict(report,status='FAIL',errors=[f'Cannot identify the release: {exc}'])
+    report.update(bits=bits,expected_shards=len(expected),expected_weight_bytes=sum(v[0] for v in expected.values()))
+    for name in REQUIRED:
+        path = folder/name
+        if not path.is_file():
+            errors.append(f'Missing required asset: {name}')
+        elif path.stat().st_size == 0:
+            errors.append(f'Empty required asset: {name}')
+        elif name.endswith('.json'):
+            try:
+                read_json(path)
+            except (ValueError, OSError) as exc:
+                errors.append(f'Cannot parse {name}: {type(exc).__name__}')
+    seen = {}
+    sizes = {'U32':4, 'BF16':2, 'F16':2, 'F32':4}
+    for name,(size,sha256) in expected.items():
+        path = folder/name
+        actual = path.stat().st_size if path.is_file() else None
+        row = {'file':name,'expected_bytes':size,'actual_bytes':actual}
+        report['files'].append(row)
+        if actual != size:
+            errors.append(f'{name}: expected {size} bytes, found {actual if actual is not None else "missing"}')
+            continue
+        try:
+            with path.open('rb') as stream:
+                length = struct.unpack('<Q',stream.read(8))[0]
+                if not 0 < length <= 16*1024*1024:
+                    raise ValueError('Invalid safetensors header size')
+                headers = json.loads(stream.read(length),object_pairs_hook=unique)
+            if not isinstance(headers,dict):
+                raise ValueError('Invalid safetensors header object')
+            headers.pop('__metadata__',None)
+            ranges = []
+            for tensor,entry in headers.items():
+                if tensor in seen:
+                    raise ValueError('Duplicate tensor across shards')
+                start,end = entry['data_offsets']
+                shape = entry['shape']
+                if not isinstance(shape,list) or type(start) is not int or type(end) is not int:
+                    raise ValueError('Invalid shape or offset types')
+                count = 1
+                for dim in shape:
+                    if type(dim) is not int or dim < 0:
+                        raise ValueError('Invalid tensor shape')
+                    count *= dim
+                if entry['dtype'] not in sizes or end-start != count*sizes[entry['dtype']]:
+                    raise ValueError('Invalid tensor size or dtype')
+                if not 0 <= start <= end <= actual-8-length:
+                    raise ValueError('Invalid tensor data offsets')
+                seen[tensor] = name
+                ranges.append((start,end))
+            offset = 0
+            for start,end in sorted(ranges):
+                if start != offset:
+                    raise ValueError('Overlapping tensor data or a payload gap')
+                offset = end
+            if offset != actual-8-length:
+                raise ValueError('Tensor payload does not fill shard')
+            row['header_check'] = 'PASS'
+            if check_hashes:
+                digest = hashlib.sha256()
+                with path.open('rb') as stream:
+                    for block in iter(lambda:stream.read(8*1024*1024),b''):
+                        digest.update(block)
+                row['sha256'] = digest.hexdigest()
+                row['sha256_check'] = 'PASS' if row['sha256'] == sha256 else 'FAIL'
+                if row['sha256'] != sha256:
+                    errors.append(f'SHA256 mismatch: {name}')
+        except (ValueError,KeyError,TypeError,OSError,struct.error) as exc:
+            errors.append(f'{name}: {exc}')
+    extra = sorted(p.name for p in folder.glob('*.safetensors') if p.name not in expected)
+    if extra:
+        errors.append(f'Unexpected root weight files: {extra}')
+    try:
+        index = read_json(folder/'model.safetensors.index.json')
+        if not isinstance(index['weight_map'],dict):
+            raise ValueError('Invalid weight map')
+        if set(index['weight_map'].values()) != set(expected):
+            errors.append(f'Index must reference exactly the {len(expected)} expected shards')
+        if seen != index['weight_map']:
+            errors.append('Available tensor headers do not match the complete index')
+        if len(index['weight_map']) != EXPECTED_TENSORS:
+            errors.append(f'Expected {EXPECTED_TENSORS} saved tensor entries')
+    except (OSError,ValueError,KeyError,TypeError):
+        errors.append('Cannot validate the checkpoint index')
+    try:
+        if config.get('quantization') != {'bits':bits,'group_size':64,'mode':'affine'}:
+            errors.append(f'Expected affine / {bits}-bit / group size 64')
+        if config.get('language_model_only') is not False:
+            errors.append('Expected the complete Swift architecture configuration')
+        if check_runtime:
+            try:
+                report['runtime'] = runtime_check(config)
+            except Exception as exc:
+                errors.append(f'Runtime check failed: {type(exc).__name__}: {exc}')
+    except (OSError,ValueError,KeyError,TypeError):
+        errors.append('Cannot validate model configuration')
+    report['hash_check'] = ('PASS' if all(row.get('sha256_check')=='PASS' for row in report['files']) else 'FAIL_OR_INCOMPLETE') if check_hashes else 'not run; add --hash to read and SHA256-check all weight bytes'
+    report['runtime_check_requested'] = check_runtime
+    report['errors'] = errors
+    report['status'] = 'FAIL' if errors else 'PASS_DOWNLOAD_AND_REQUESTED_CHECKS_ONLY'
+    return report
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('folder',type=Path)
+    parser.add_argument('--hash',action='store_true',help='Stream-read every shard and compare its original SHA256')
+    parser.add_argument('--runtime',action='store_true',help='Check the installed Python MLX-LM dispatcher; does not instantiate the model')
+    args = parser.parse_args()
+    result = check(args.folder,args.hash,args.runtime)
+    print(json.dumps(result,indent=2))
+    return 1 if result['errors'] else 0
+
+if __name__ == '__main__':
+    sys.exit(main())