Refresh OrbitQuant model cards

README.md

@@ -19,32 +19,24 @@ OrbitQuant is a calibration-free post-training quantization method for image and
 Install OrbitQuant and the Hugging Face runtime dependencies:
 
 ```bash
-pip install git+https://github.com/iamwavecut/OrbitQuant.git diffusers transformers accelerate huggingface_hub safetensors
+pip install "orbitquant[hf]"
 ```
 
-Load the base Diffusers pipeline, download this model repository as an OrbitQuant artifact, then patch the transformer component:
+Download this model repository as an OrbitQuant artifact, then load the source Diffusers pipeline with the quantized component patched in:
 
 ```python
 import torch
-from diffusers import ZImagePipeline
 from huggingface_hub import snapshot_download
-from orbitquant import load_quantized_pipeline_component
+from orbitquant import load_quantized_pipeline_from_artifact
 
-base_model = "Tongyi-MAI/Z-Image-Turbo"
 artifact_id = "WaveCut/Z-Image-Turbo-OrbitQuant-W4A4"
 
 artifact_dir = snapshot_download(artifact_id, repo_type="model")
-pipe = ZImagePipeline.from_pretrained(
-    base_model,
-    torch_dtype=torch.bfloat16,
-)
-load_quantized_pipeline_component(
-    pipe,
+pipe = load_quantized_pipeline_from_artifact(
     artifact_dir,
-    component="transformer",
+    torch_dtype=torch.bfloat16,
     device="cuda",
 )
-pipe.to("cuda")
 
 image = pipe(
     prompt="A precise product photo of a red ceramic mug on a wooden desk",
@@ -56,6 +48,8 @@ image = pipe(
 image.save("z-image-orbitquant.png")
 ```
 
+`runtime_mode="auto_fused"` is the default optimized runtime. On CUDA it tries the native packed low-bit matmul kernel first, then Triton packed matmul. On MPS it requires the native Metal packed matmul kernel. Use `runtime_mode="dequant_bf16"` only as an explicit compatibility/debug reference path.
+
 ## Native Settings
 
 Use these settings when comparing this artifact against the BF16 source model or the visual assets below:
@@ -75,9 +69,9 @@ Use these settings when comparing this artifact against the BF16 source model or
 - Release-grade GenEval metrics: not included in this artifact.
 - The model card reports artifact-level validation status only.
 
-## Native Validation Proof
+## Native Validation Evidence
 
-The compact benchmark summary records native BF16-vs-OrbitQuant evidence for the comparison matrix below. Raw generation records are kept local-only and are not part of this published artifact.
+The compact benchmark summary records native BF16-vs-OrbitQuant evidence for the comparison matrix below. Detailed per-sample generation records are retained outside this compact artifact.
 
 | Evidence | Value |
 | --- | --- |
@@ -139,5 +133,5 @@ 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.
-- Runtime mode may dequantize packed weights before BF16 matmul. Disk artifacts are compact, while runtime VRAM depends on the selected backend.
+- 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 @@
-d179a1ba293c3914b7b359320f3b2248ca8f3a9279a26d4ab0d674ead60839b7  README.md
+3841d6da80aac3eba4641c8e4836ef55c2b40ace84228c09b9c2cb31c8a95fbc  README.md
 2a00b76af1f8efa1c65d838331fc918d1da34b92a62420def947295d4a73cf4a  assets/image_generation_comparison_matrix.webp
 e86d99c6823b417b8a990b8576e3cb86e3eb18e9e20899183b77548fc8497770  benchmark/summary.json
 17d55569ad22825174ad7db10e981cab44a0c58e0a50253fa8fcc08476d3175c  model.safetensors