Qwen-Image-Layered-MRP-MLX/CHANGELOG.md

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[0.9.0] - 2025-06-28

MFLUX v.0.9.0 Release Notes

Major New Features

📸 FLUX.1 Kontext

• Added FLUX.1 Kontext support: Official Black Forest Labs model for character consistency, local editing, and style reference
• New command: mflux-generate-kontext for image-guided generation with text instructions
• Advanced image editing capabilities: Sequential editing, style transfer, character consistency, and local modifications
• Comprehensive documentation: Detailed prompting guide with tips, templates, and best practices
• Automatic model handling: Uses dev-kontext model configuration with optimized defaults

🖼️ Scale Factor Support for Image Upscaling

• Enhanced upscaling dimensions: Added support for scale factors (e.g., 2x, 1.5x) in addition to absolute pixel values
• Mixed dimension types: Ability to combine scale factors and absolute values (e.g., --height 2x --width 1024)
• Auto dimension handling: Use auto to preserve original image dimensions
• Safety warnings: Automatic warnings when requested dimensions exceed recommended limits
• Pixel-perfect scaling: Scale factors automatically align to 16-pixel boundaries for optimal results

⌨️ Shell Completions

• ZSH completion support: Full tab completion for all mflux CLI commands and arguments
• Smart completions: Context-aware completions for model names, quantization levels, LoRA styles, and file paths
• Easy installation: Simple mflux-completions command for automatic setup
• Dynamic generation: Completions stay in sync with code changes and new commands
• Comprehensive coverage: Supports all 15+ mflux commands with proper argument validation

🗂️ Cache Management Improvements

• Platform-native caching: Uses platformdirs for macOS-idiomatic cache locations (~/Library/Caches/mflux/)
• Automatic migration: Seamless migration from legacy ~/.cache/mflux to new platform-appropriate locations
• Environment variable support: MFLUX_CACHE_DIR for custom cache locations
• Improved organization: Separate cache directories for different types of data (models, LoRAs, etc.)
• Backward compatibility: Automatic symlink creation for legacy path compatibility

Breaking Changes

🔧 Python API Class Naming Standardization

• Class rename: FluxInContextFill is now Flux1InContextFill to follow consistent naming convention
• Class rename: FluxConceptFromImage is now Flux1ConceptFromImage to follow consistent naming convention
• Breaking change for library users: If you import these classes directly in Python code, you may need to update your imports
• CLI tools unaffected: All command-line tools (mflux-generate-*) continue to work without changes

Contributors

Contributors:

• Anthony Wu (@anthonywu): Scale factor support, shell completions, cache refactor
• Filip Strand (@filipstrand): Kontext support, class naming standardization, core development

[0.8.0] - 2025-06-14

MFLUX v.0.8.0 Release Notes

Experimental AI Features

👗 CatVTON (Virtual Try-On)

• [EXPERIMENTAL] Added virtual try-on capabilities using in-context learning via mflux-generate-in-context-catvton
• Support for person image, person mask, and garment image inputs for comprehensive virtual clothing try-on
• Automatic prompting for virtual try-on scenarios with optimized default prompts
• Side-by-side generation showing garment product shot alongside styled result
• AI-powered virtual clothing fitting with realistic lighting and fabric properties

✏️ IC-Edit (In-Context Editing)

• [EXPERIMENTAL] Added natural language image editing capabilities via mflux-generate-in-context-edit
• Natural language image editing using simple text instructions like "make the hair black" or "add sunglasses"
• Automatic diptych template formatting for optimal editing results
• Optimal resolution auto-sizing for 512px width (the resolution IC-Edit was trained on)
• Specialized LoRA automatically downloaded and applied for enhanced editing capabilities

Enhanced Generation Control

🔎 Image Upscaling

• Built-in upscaling capabilities: Enhanced image quality and resolution enhancement for generated images
• Seamless integration with existing generation workflow
• Professional-grade upscaling for production-ready outputs

Interpretability research

🧠 Concept Attention

• Enhanced image generation control: Fine-grained control over image generation focus areas using attention-based concepts
• Improved composition and subject handling for more precise artistic direction
• Advanced attention mechanisms for better understanding of prompt concepts

Workflow & Performance Improvements

🪫 Battery Saver

• Power management: Automatic power optimization during extended generation sessions
• Configurable power-saving modes specifically designed for laptop users
• Smart resource management for long-running batch operations

📝 Prompt File Support

• File-based prompt input: Batch operations via --prompt-file for large-scale generation projects
• Dynamic prompt updates for large batch generation workflows
• Support for external prompt management and automation systems

🔄 Redux Function Balancing

• Enhanced Redux capabilities: Improved control over image-to-image transformation strength
• Better quality variations with adjustable parameters for more predictable results
• Refined Redux algorithm for more natural image variations

📥 Stdin Prompt Support

• LLM Integration Ready: Added support for providing prompts via stdin using --prompt -
• Enables seamless integration with LLMs and other text generation tools
• Supports both single-line and multi-line prompts through stdin
• Perfect for automation workflows and dynamic prompt generation
• Example usage: echo "A beautiful landscape" | mflux-generate --prompt -

Developer Experience

🔧 LORA_LIBRARY_PATH Improvements

• Unix-style resource discovery: Enhanced LoRA library path handling for better organization
• Improved path handling for LoRA weight discovery across multiple directories
• Better cross-platform compatibility for LoRA management

🧪 Testing & Documentation

• New command-line arguments for both experimental features with comprehensive help
• Comprehensive argument parser tests for new functionality
• Updated documentation with experimental feature warnings and usage guidelines
• Added note about upcoming FLUX.1 Kontext model from Black Forest Labs

Architecture Improvements

📚 Documentation Structure

• Refactored "In-Context LoRA" section to "In-Context Generation" with clear subcategories
• Enhanced documentation structure for better organization and user navigation
• Improved categorization of experimental vs stable features

🔄 Code Architecture Changes

• Class rename: Flux1InContextLora is now Flux1InContextDev to better reflect the dev model variant
• Module reorganization: Moved from mflux.community.in_context_lora.flux_in_context_lora to mflux.community.in_context.flux_in_context_dev
• Breaking change for library users: If you import the class directly, update your imports accordingly

⚡ Performance Optimizations

• Updated MLX dependency to latest version for improved performance and stability
• Removed PyTorch dependency for DepthPro model, significantly reducing installation requirements
• Streamlined dependencies for faster installation and reduced disk usage

Experimental Notice

⚠️ Important: CatVTON and IC-Edit features are experimental and may be removed or significantly changed in future updates. These features represent cutting-edge AI capabilities that are still under active development.

Contributors

Special thanks to the following contributors for their exceptional work since v0.7.1:

• Anthony Wu (@anthonywu): Battery Saver implementation, Prompt File Support, Stdin Prompt Support, LORA_LIBRARY_PATH improvements
• Alessandro (@azrahello): Redux Function Balancing enhancements
• Filip Strand (@filipstrand): Core development, experimental features integration, infrastructure improvements

[0.7.1] - 2025-05-06

MFLUX v.0.7.1 Release Notes

New Features

🎭 Multi-LoRA Support

• Multiple LoRA Loading: Added support for loading multiple LoRA adapters simultaneously when using the in-context feature
• Enhanced creative flexibility by combining multiple artistic styles in a single generation
• Reference: GitHub Issue #178

[0.7.0] - 2025-04-25

MFLUX v.0.7.0 Release Notes

Major New Features

🖌️ FLUX.1 Tools | Fill

• Added support for the FLUX.1-Fill model for inpainting and outpainting
• Introduced mflux-generate-fill command-line tool for selective image editing
• Implemented interactive mask creation tool to easily mark areas for regeneration
• Added outpainting capabilities with customizable canvas expansion
• Includes helper tools for creating outpaint image canvases and masks

🔍 FLUX.1 Tools | Depth

• Added support for the FLUX.1-Depth model for depth-conditioned image generation
• Implemented Apple's ML Depth Pro model in MLX for state-of-the-art depth map extraction
• Added mflux-generate-depth and mflux-save-depth command-line tools
• Added ability to use either auto-generated depth maps or custom depth maps

🔄 FLUX.1 Tools | Redux

• Added Redux tool as a new image variation technique
• Implemented a different approach compared to standard image-to-image generation
• Uses image embedding joined with T5 text encodings for more natural variations
• Added Redux-specific weight handlers and initialization

New Models

🔎 Apple ML Depth Pro

• Added native MLX implementation of Apple's ML Depth Pro model for both separate use, and as a part of the Depth tool functionality

🖼️ Google SigLIP Vision Transformer

• Added SigLIP vision model for the Redux functionality

Architecture Improvements

💾 Weight Management Improvements

• Added support for saving MFLUX version information in model metadata

🧠 Memory Optimization

• Additional improvements to the --low-ram option
• Better memory management for image generation models

Contributors

• @anthonywu
• @ssakar
• @akx

[0.6.2] - 2025-03-13

MFLUX v.0.6.2 Release Notes

Bug Fixes

💾 Model Saving Fix

• Fixed local model saving: Resolved bug preventing users from saving models locally with mflux-save
• Restored full functionality for local model storage and management

[0.6.1] - 2025-03-11

MFLUX v.0.6.1 Release Notes

Bug Fixes

🛑 Image Generation Interruption

• Fixed interruption flow: Properly handles interruptions during image generation, ensuring graceful stops even when no callbacks are registered
• Keyboard interrupt handling: Ensures image generation can be stopped via Ctrl+C in all diffusion model variants (standard Flux, ControlNet, and In-Context LoRA)
• Relocated StopImageGenerationException from stepwise handler to main generation functions for more robust interruption system

Test Stability Improvements

🧪 Test Reliability

• Fixed sporadic test failures: Resolved intermittent failures in auto-seeds test case when using random seed count of 1
• Improved test consistency and reliability

Code Quality Improvements

🔧 Code Standards

• Formatting and linting fixes: Fixed various formatting issues that were missed in the v0.6.0 release
• Enhanced code consistency and maintainability

[0.6.0] - 2025-03-05

MFLUX v.0.6.0 Release Notes

Major New Features

🌐 Third-Party HuggingFace Model Support

• Comprehensive ModelConfig refactor to support compatible HuggingFace dev/schnell models
• Added ability to use models like Freepik/flux.1-lite-8B-alpha and shuttleai/shuttle-3-diffusion
• New --base-model parameter to specify which base architecture (dev or schnell) a third-party model is derived from
• Maintains backward compatibility while opening up the ecosystem to community-created models

🎭 In-Context LoRA

• Added support for In-Context LoRA, a powerful technique that allows you to generate images in a specific style based on a reference image without requiring model fine-tuning
• Introduced a new command-line tool: mflux-generate-in-context
• Includes 10 pre-defined styles from the Hugging Face ali-vilab/In-Context-LoRA repository
• Detailed documentation on how to use this feature effectively with prompting tips and best practices

🔌 Automatic LoRA Downloads

• Added ability to automatically download LoRAs from Hugging Face when specified by repository ID
• Simplifies workflow by eliminating the need to manually download LoRA files before use

🧠 Memory Optimizations

• Added --low-ram option to reduce GPU memory usage by constraining the MLX cache size and releasing text encoders and transformer components after use
• Implemented memory saver for ControlNet to reduce RAM requirements
• General memory usage optimizations throughout the codebase

🗜️ Enhanced Quantization Options

• Added support for 3-bit and 6-bit quantization (requires mlx > v0.21.0)
• Expanded quantization options now include 3, 4, 6, and 8-bit precision

⚠️Breaking changes

Previously saved quantized models will not work for v.0.6.0 and later. See #149 for more details.

Interface Improvements

🔧 Modified Parameters

• The previous --init-image-path parameter is now --image-path
• The previous --init-image-strength parameter is now --image-strength

🖼️ Image Generation Enhancements

• Added --auto-seeds option to generate multiple images with random seeds in a single command
• Added option to override previously saved test images
• Added --controlnet-save-canny option to save the Canny edge detection reference image used by ControlNet
• Improved handling of edge cases for img2img generation

🔄 Callback System

• Implemented a general callback mechanism for more flexible image generation pipelines
• Added support for before-loop callbacks to accept latents
• Enhanced StepwiseHandler to include initial latent

Architecture Improvements

🏗️ Code Refactoring

• Removed 'init' prefix for a more general interface
• Removed ConfigControlnet - the controlnet_strength attribute is now on Config
• Simplified quantization by removing unnecessary class predicates
• Refactored model configuration system
• Refactored transformer blocks for better maintainability
• Unified attention mechanism in single and joint attention blocks
• Added support for variable numbers of transformer blocks
• Optimized with fast SDPA (Scaled Dot-Product Attention)
• Added PromptCache for small optimization when generating with repeated prompts

🧰 Developer Tools

• Added Batch Image Renamer tool as an isolated uv run script
• Added descriptive comments for attention computations

Compatibility Updates

• Updated to support the latest mlx version
• Fixed compatibility issues with HuggingFace dev/schnell models

Bug Fixes

• Fixed handling of edge cases for img2img generation
• Various small fixes and improvements throughout the codebase

Contributors

• @anthonywu
• @ssakar
• @azrahello
• @DanaCase

[0.5.1] - 2024-12-23

MFLUX v.0.5.1 Release Notes

Bug Fixes

🔧 LoRA Loading Fix

• Quantized model LoRA compatibility: Fixed critical bug where locally saved quantized models failed to set LoRA weights
• Users can now successfully combine local quantized models with external LoRA adapters
• Improved reliability for advanced workflows combining quantization and LoRA fine-tuning

[0.5.0] - 2024-12-22

MFLUX v.0.5.0 Release Notes

Major New Features

🎛️ DreamBooth Fine-tuning

• DreamBooth support: Introduced V1 of fine-tuning support in MFLUX
• Enables custom model training for personalized image generation
• Full fine-tuning pipeline with training configuration options

Architecture Improvements

🔧 Weight Management Overhaul

• Rewritten LoRA handling: Completely rewritten LoRA weight handling system
• Improved performance and reliability for LoRA operations
• Better support for complex LoRA workflows

Developer Experience

🧪 Testing & Quality

• Enhanced test coverage: Added comprehensive tests for new and existing features
• Multi-LoRA testing support
• Local model saving test coverage

📊 New Dependencies

• Matplotlib integration: Added matplotlib for visualizing training loss during fine-tuning
• TOML support: Added TOML library for better handling of MFLUX version metadata
• Enhanced configuration management

[0.4.1] - 2024-10-29

MFLUX v.0.4.1 Release Notes

Bug Fixes

🐛 Image Generation Fixes

• Img2img resolution fix: Fixed img2img functionality for non-square image resolutions
• Improved compatibility with various aspect ratios

[0.4.0] - 2024-10-28

MFLUX v.0.4.0 Release Notes

Major New Features

🖼️ Image-to-Image Generation

• Img2Img Support: Introduced the ability to generate images based on an initial reference image
• Transform existing images using AI-powered generation techniques
• Control the strength of transformation to balance between original image preservation and creative generation
• Perfect for iterating on designs and creating variations of existing artwork

📊 Metadata-Driven Generation

• Image Generation from Metadata: Added support to generate images directly from provided metadata files
• Streamlined workflow for recreating images with specific parameters
• Enhanced reproducibility for professional and research workflows
• Automated parameter loading from previously generated images

🔍 Real-time Generation Monitoring

• Progressive Step Output: Optionally output each step of the image generation process for real-time monitoring
• Visual feedback during generation for better understanding of the AI process
• Debug and fine-tune generation parameters by observing intermediate steps
• Educational tool for understanding diffusion model progression

Developer Experience Improvements

🛠️ Enhanced Command-Line Interface

• Improved argument handling: Enhanced parsing and validation for command-line arguments
• Better error messages and user guidance for parameter configuration
• More intuitive command structure for complex generation workflows

🧪 Testing & Quality Assurance

• Automated Testing: Added comprehensive automatic tests for image generation and command-line argument handling
• Improved reliability and stability for all generation modes
• Continuous integration testing for better code quality

🔧 Development Workflow

• Pre-Commit Hooks: Integrated pre-commit hooks with ruff, isort, and typo checks for better code consistency
• Enhanced developer experience with automated code quality checks
• Streamlined contribution process for open source development

[0.3.0] - 2024-09-24

MFLUX v.0.3.0 Release Notes

Major New Features

🕹️ ControlNet Support

• ControlNet Canny support: Added Canny edge detection ControlNet functionality for precise image control
• Enhanced control over image generation with edge-guided conditioning

Model Export Improvements

📦 Advanced Model Export

• Quantized model export with LoRA: Added ability to export quantized models with LoRA weights baked in
• Streamlined deployment for fine-tuned models

Developer Experience

🛠️ Development Tools

• Enhanced development workflow: Improved developer experience with uv, ruff, makefile, pre-commit hooks
• Better code quality tools and automated checks
• Streamlined contribution process

Legal & Licensing

⚖️ Open Source License

• Official MIT license: Established clear open source licensing for the project
• Legal clarity for users and contributors

[0.2.1] - 2024-09-14

MFLUX v.0.2.1 Release Notes

Improvements

🔧 LoRA Enhancements

• Enhanced LoRA support: Improved compatibility and performance for LoRA weight loading
• Better integration with existing workflows
• Refined handling of LoRA adapters

[0.2.0] - 2024-09-07

MFLUX v.0.2.0 Release Notes

Major Milestone

🚀 Official PyPI Release

• First official PyPI release: pip install mflux - making MFLUX easily installable for everyone
• Big thanks to @deto for letting us have the "mflux" name on PyPI!

New Features

🎨 Core Image Generation

• Command-line tools: Introduced dedicated commands for better user experience
  • mflux-generate for generating images
  • mflux-save for saving quantized models to disk
• 🗜️ Quantization support: Added support for quantized models with 4-bit and 8-bit precision
• LoRA weights: Added support for loading trained LoRA (Low-Rank Adaptation) weights
• Automatic metadata: Images now automatically save metadata when generated

Developer Experience

📦 Distribution

• Official packaging and distribution through PyPI
• Simplified installation process for end users
• Professional project structure and naming