Document RealVisXL provenance, conversion, and runtime settings

README.md

@@ -1,41 +1,62 @@
 ---
 license: openrail++
+base_model: SG161222/RealVisXL_V5.0_Lightning
+library_name: coreml
 tags:
-- text-to-image
-- stable-diffusion-xl
-- dreamshaper
-- lightning
 - coreml
-- apple-neural-engine
-- palettized
-base_model:
-- Lykon/dreamshaper-xl-lightning
-pipeline_tag: text-to-image
-library_name: ml-stable-diffusion
+- stable-diffusion-xl
+- text-to-image
+- image-to-image
+- ios
+- localmuse
 ---
 
-# DreamShaper XL Lightning - Core ML 6-bit
+# RealVisXL V5.0 Lightning — 6-bit split Core ML
+
+Self-contained, compiled SDXL package prepared for on-device use by the LocalMuse iOS app. The repository stays private until the artifact manifest and anonymous downloads are verified.
+
+## Provenance
+
+- Source UNet: [`SG161222/RealVisXL_V5.0_Lightning`](https://huggingface.co/SG161222/RealVisXL_V5.0_Lightning)
+- Pinned source revision: `f4454158cedaab9f0688c199561d6c92525f3a85`
+- Source fp16 UNet LFS SHA-256: `1143cd2aaf65d24af34b5699d090aed724f6c0978c2ec5a5f56821ccb36260ce`
+- License: CreativeML Open RAIL++-M (`LICENSE.md`), inherited from the source model and SDXL base.
+
+The RealVisXL UNet was converted from the pinned source above. The text encoders, VAE encoder/decoder, tokenizer vocabulary, and merges are standard SDXL components reused byte-for-byte from [`LocalMuseAI/coreml-dreamshaper-xl-lightning-6bit`](https://huggingface.co/LocalMuseAI/coreml-dreamshaper-xl-lightning-6bit) revision `736408cecf59b3b81a8b2a900cdd5dbf94c34c2a`. Only the UNet contains RealVisXL-specific weights.
+
+## Conversion
+
+- Apple converter: [`apple/ml-stable-diffusion`](https://github.com/apple/ml-stable-diffusion) revision `e12202c1f6405b83918b58a5d097cd61e3e1f702`
+- PyTorch `2.4.0`
+- coremltools `8.0`
+- Diffusers `0.30.2`
+- Transformers `4.44.2`
+- huggingface_hub `0.24.6`
+- NumPy `1.23.5`
+- Resolution: fixed `1024 × 1024` (`128 × 128` latent)
+- Classifier-free-guidance batch: `2`
+- Attention implementation: `SPLIT_EINSUM`
+- UNet storage: mixed Float16 and 6-bit palettized weights
+- Minimum Core ML deployment target: iOS 17
+- UNet split into two independently compiled chunks below 1 GiB each
 
-An iOS-oriented Core ML distribution of [Lykon/DreamShaper XL Lightning](https://huggingface.co/Lykon/dreamshaper-xl-lightning), prepared for on-device inference in the LocalMuse app.
+The source model's fp16 UNet was loaded directly without downloading unrelated full-precision weights, converted through Apple's Stable Diffusion implementation, palettized before chunking, bisected with coremltools, and compiled with `xcrun coremlc`.
 
-No model training was performed by LocalMuseAI. The original model weights and authorship belong to Lykon and the upstream SDXL/SDXL-Lightning contributors. This repository only distributes the compiled Core ML representation and mobile-oriented weight palettization.
+## Runtime settings
 
-## Runtime format
+The source model card recommends 5 inference steps, CFG 1–2, and a DPM++ SDE Karras scheduler. LocalMuse uses:
 
-- Native resolution: 1024 x 1024
-- Apple Core ML compiled models (`.mlmodelc`)
-- SPLIT_EINSUM attention
-- Two 6-bit palettized UNet chunks, each below 1 GiB
-- 6-bit palettized second text encoder
-- VAE decoder for text-to-image
-- VAE encoder for image-to-image and face-detail workflows
-- CLIP vocabulary and merges
+- Steps: `5`
+- CFG: `1.5`
+- Scheduler: second-order DPM-Solver++ multistep
+- Timestep spacing: Karras
+- Batch size: `1` image (the UNet internally uses batch 2 for CFG)
+- UNet: Neural Engine preferred
+- VAE: GPU preferred
+- Minimum device memory exposed by the app: 8 GiB
 
-LocalMuse uses a four-step DPM schedule, Neural Engine denoising, and GPU-preferred VAE execution. The package is intended for recent iPhones with at least 8 GiB of physical memory.
+## Verification
 
-## License and attribution
+Both chunks compile successfully with Xcode `coremlc`. Their named input/output feature sets and tensor shapes match the SDXL split-UNet contract already used by LocalMuse. The model is distributed as direct authenticated files; the app pins every URL to a repository commit and verifies the exact SHA-256 and byte count before installation.
 
-- Base model: [Lykon/dreamshaper-xl-lightning](https://huggingface.co/Lykon/dreamshaper-xl-lightning)
-- Core ML tooling: [apple/ml-stable-diffusion](https://github.com/apple/ml-stable-diffusion)
-- License: CreativeML Open RAIL++-M; see `LICENSE.md`
-- This mirror imposes no additional restrictions.
+Real-device image quality and thermal behavior should still be validated before shipping a production App Store build.