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

@@ -34,6 +34,17 @@ converted with the official Apple MLX-LM converter using 4 bits and group size 6
 Swift 1.5 is UkisAI's reasoning-efficient Qwen3.8-27B derivative, focused on stronger
 long-horizon, agentic and coding performance while using fewer thinking tokens.
 
+**Runtime compatibility:** this complete checkpoint requires the supplied architecture patch
+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 **15.83 GB (14.74 GiB) across 3 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.
 
 ## Download the complete model
@@ -60,8 +71,8 @@ model. Those test files are now archived under `compatibility/mac-check/fixtures
 to keep them out of model-file discovery. Model weights are unchanged.
 
 **Runtime requirement:** use the included MLX-LM patch and [loading instructions](USAGE.md).
-Stock MLX-LM and GUI integrations that cannot apply the patch have not been validated
-for this complete checkpoint. Full-model generation on a 24 GB Mac has not been
+The tested stock MLX-LM 0.32.0 loader cannot load this complete checkpoint;
+GUI integrations must supply a compatible loader and have not been validated. Full-model generation on a 24 GB Mac has not been
 validated; the weights require additional memory for the runtime, cache and macOS.
 
 ## Demo

TROUBLESHOOTING.md

@@ -0,0 +1,79 @@
+# Check this download and its runtime
+
+This release needs **all 3 shards (15.83 GB (14.74 GiB))**, its index/config/tokenizer
+assets, and the supplied architecture patch. 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-4bit-MLX`:
+
+```bash
+python Swift-1.5-4bit-MLX/check_download.py Swift-1.5-4bit-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 the supplied architecture patch in the pinned Python
+environment. Then, in that same environment:
+
+```bash
+python Swift-1.5-4bit-MLX/check_download.py Swift-1.5-4bit-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

@@ -31,19 +31,29 @@
     },
     {
       "path": "README.md",
-      "bytes": 9378,
-      "sha256": "ff4ca8864c6280d1cf22a9007e9785a5c169a98b2451956fe31b5fae2813c48c"
+      "bytes": 10074,
+      "sha256": "fc7a25233fe1f32a53318716b7c7a5a00818603cd72285ffae990958f9e3e030"
+    },
+    {
+      "path": "TROUBLESHOOTING.md",
+      "bytes": 4360,
+      "sha256": "6460abf4aa4d2de46f07ce8dfa095476467eb466c6250c727ba0d6f2c77399eb"
     },
     {
       "path": "USAGE.md",
-      "bytes": 5383,
-      "sha256": "cb883ee96b83b51dadb4b895478a35e07d218fcab25668aeaf4ecb4849773e01"
+      "bytes": 5924,
+      "sha256": "70e4b505d7acb75d33774e19b4b6202e5e45f0dcaf0f5973d6ea73f5d618a941"
     },
     {
       "path": "chat_template.jinja",
       "bytes": 8952,
       "sha256": "c3cf9e34abf4f9e36c2d72165aa9c132d3e2a725b6c2586aaa3a8af9d7a81041"
     },
+    {
+      "path": "check_download.py",
+      "bytes": 9658,
+      "sha256": "1e424a32bb015431df22b8f058aa18de116ae63e0440d60424792a1cf2fd4018"
+    },
     {
       "path": "compatibility/MLX-LM-LICENSE",
       "bytes": 1066,
@@ -270,7 +280,8 @@
       "sha256": "ce99b4cb2983d118806ce0a8b777a35b093e2000a503ebde25853284c9dfa003"
     }
   ],
-  "total_bytes_excluding_manifest": 15859824848,
+  "total_bytes_excluding_manifest": 15859840103,
   "manifest_self_excluded": true,
-  "packaging_update": "2026-09-24: diagnostic fixtures archived; model weights unchanged"
+  "packaging_update": "2026-09-24: diagnostic fixtures archived; model weights unchanged",
+  "diagnostic_update": "2026-09-25: clarify required runtime; add download/runtime checker; weights unchanged"
 }

USAGE.md

@@ -21,6 +21,7 @@ python -m pip install 'huggingface_hub==1.31.0'
 SWIFT_MLX_REVISION="$(python -c 'import json, urllib.request; print(json.load(urllib.request.urlopen("https://huggingface.co/api/models/ukisai/Swift-1.5-4bit-MLX"))["sha"])')"
 hf download ukisai/Swift-1.5-4bit-MLX --revision "$SWIFT_MLX_REVISION" --local-dir Swift-1.5-4bit-MLX
 hf cache verify ukisai/Swift-1.5-4bit-MLX --revision "$SWIFT_MLX_REVISION" --local-dir Swift-1.5-4bit-MLX --fail-on-missing-files
+python Swift-1.5-4bit-MLX/check_download.py Swift-1.5-4bit-MLX
 git clone https://github.com/ml-explore/mlx-lm.git swift15-mlx-lm
 git -C swift15-mlx-lm checkout --detach c69d1288440a0dc4e6401fc417098b07598dccd5
 git -C swift15-mlx-lm apply --check ../Swift-1.5-4bit-MLX/compatibility/swift15-mlx-lm.patch
@@ -50,6 +51,17 @@ pip install 'mlx[cpu]==0.32.2' 'transformers==5.14.1' 'huggingface_hub==1.31.0'
 pip install -e ./swift15-mlx-lm
 ```
 
+Before generating, check the Python environment that will actually run the model:
+
+```bash
+python Swift-1.5-4bit-MLX/check_download.py Swift-1.5-4bit-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())