Document OrbitQuant 0.4.0 on-the-fly conversion

README.md

@@ -19,7 +19,7 @@ OrbitQuant is a calibration-free post-training quantization method for image and
 Install OrbitQuant and the Hugging Face runtime dependencies:
 
 ```bash
-pip install "orbitquant[hf,kernels]>=0.2.0"
+pip install "orbitquant[hf,kernels]>=0.4.0"
 ```
 
 Download this model repository as an OrbitQuant artifact, then load the source Diffusers pipeline with the quantized component patched in:
@@ -49,6 +49,31 @@ image = pipe(
 image.save("z-image-orbitquant.png")
 ```
 
+### Convert the source checkpoint on load
+
+For a safetensors source checkpoint, OrbitQuant can row-stream the denoiser into packed weights through the normal Diffusers loader. Use sequential offload by replacing the final call with `pipe.enable_sequential_cpu_offload()`.
+
+```python
+import torch
+import orbitquant
+from diffusers import DiffusionPipeline
+from orbitquant import (
+    OrbitQuantConfig,
+    build_diffusers_pipeline_quantization_config,
+)
+
+qconfig = build_diffusers_pipeline_quantization_config(
+    OrbitQuantConfig(target_policy="auto"),
+    components="transformer",
+)
+pipe = DiffusionPipeline.from_pretrained(
+    "Tongyi-MAI/Z-Image-Turbo",
+    quantization_config=qconfig,
+    torch_dtype=torch.bfloat16,
+)
+pipe.enable_model_cpu_offload()
+```
+
 `runtime_mode="auto_fused"` is the default optimized runtime. On CUDA, the `kernels` extra provides the Triton packed fallback; a locally built native CUDA package is preferred automatically when installed. On MPS, build and install the native Metal package from the OrbitQuant source tree. See the [OrbitQuant runtime instructions](https://github.com/iamwavecut/OrbitQuant/blob/main/docs/kernel-audit.md#local-native-package). Use `runtime_mode="dequant_bf16"` only as an explicit compatibility/debug reference path.
 
 ## Native Settings
@@ -167,5 +192,6 @@ The following assets are stored in this artifact and compare the BF16 base gener
 ## Limitations
 
 - This is a transformer-component artifact; load it into the source pipeline as shown above.
+- Guaranteed on-the-fly bounded-memory conversion requires a safetensors source checkpoint. Unknown architectures have structural coverage only and require policy inspection plus quality validation.
 - CUDA and MPS `auto_fused` inference requires a packed matmul kernel and fails loudly when the required kernel is unavailable. The explicit `dequant_bf16` reference mode materializes dequantized weights before BF16 matmul.
 - Quality depends on the source model and bit setting. Very low-bit settings can degrade prompt following or visual detail.

SHA256SUMS

@@ -1,4 +1,4 @@
-dd1bc37e14ef1847cfea1213eea62c85129515be5fb98cf26631f5dbc1d8d488  README.md
+6dc2ccf5a97197b69383c07ec94989900aa5826b046297ba9575f413f2d20a5a  README.md
 356d2edc39b6c6d55c357b9cadcf999b2b712fbb56975f5a64847d72dc5f6d4c  assets/image_generation_comparison_matrix.webp
 c47ce5750ec67382f1011fd6094722db671ebef7ecff1248d04b384a2808fd8f  benchmark/summary.json
 13e6cfb9a08f889f2b09acd8a467af246819742d72c653d2b66098b2fcca6da8  model.safetensors