mflux-model-porting

Port a diffusers model to MLX by working backwards from the image: validate VAE decode first using exported reference latents, then the transformer loop and scheduler, then the text encoder. Lock each component with deterministic tests before refactoring toward mflux style.

PyTorch and MLX RNGs differ, so matching integer seeds will not produce identical noise. Export the exact initial noise or latents from the reference implementation using mx.save and load them in MLX with mx.load for strict parity checks.

An MLX out-of-memory error on sensible inputs like 1024x1024 usually indicates a porting mistake rather than a hardware limit. Re-check tensor shapes and memory-heavy operations in the ported code before assuming a genuine resource constraint.

Silent zero-key LoRA loads happen when the LoRA mapping does not cover the export key convention used by the file. Support multiple conventions including diffusers, PEFT .default.weight, and kohya diffusion_model.* aliases, and add fast tests with real community LoRA filenames.

A new mflux model requires a pyproject.toml CLI entry, a ModelConfig entry with aliases and defaults, a WeightDefinition, routing in save.py, README updates, and a CI manifest overlay via scripts/ci_extract_models.py. Training support additionally needs a training adapter and example JSON config.

Add mx.compile and other performance optimizations only after deterministic parity tests pass. Premature optimization during the initial port obscures correctness bugs, so keep the first implementation simple and explicit until outputs are locked.