v0.4.0: Critical Image Normalization Fix

[0.4.0] - 2025-12-17

Fixed

• CRITICAL: Image Color and Contrast Bug
  • Fixed incorrect image saving in visualization.py that caused severe contrast issues
  • Expander outputs images in [-1, 1] range, but save_image() was treating them as [0, 1]
  • This caused negative pixel values to be clamped to black, crushing 50% of the dynamic range
  • Added normalize=True and value_range=(-1, 1) to all save_image() calls
  • Affected functions: safe_vae_sample(), save_sample_images()
  • Impact: All training sample images and generated images now have correct colors and contrast
  • Files: src/fluxflow/utils/visualization.py
  • Note: fluxflow-ui and fluxflow-comfyui were not affected (they handle conversion manually)

Added

• Model Versioning System

  • Explicit model version metadata stored alongside checkpoints
  • Automatic version detection and routing to appropriate loaders
  • Backward compatibility with legacy checkpoints (auto-detection)
  • Forward compatibility detection (clear errors for newer models)
  • Semantic versioning support (MAJOR.MINOR.PATCH)
  • Architecture metadata eliminates config inference
  • Checksum validation for integrity verification
  • Files: src/fluxflow/models/versioning.py, docs/VERSIONING.md, docs/MIGRATION.md
  • Migration tool: scripts/migrate_checkpoints.py for upgrading legacy checkpoints
  • API Changes:
    • FluxPipeline.from_pretrained() gains use_versioning parameter (opt-in, default: False)
    • FluxFlowPipeline.from_pretrained() gains use_versioning parameter (opt-in, default: False)
    • save_model() gains save_metadata, model_version, and training_info parameters
    • New functions: load_versioned_checkpoint(), save_versioned_checkpoint()
  • Testing: Comprehensive unit tests in tests/unit/test_versioning.py

• CFG Support in Sample Generation

  • Added use_cfg and guidance_scale parameters to save_sample_images() function
  • New _generate_with_cfg() helper function for CFG-guided sample generation
  • Enables classifier-free guidance during training sample generation
  • Default guidance scale: 5.0 (balanced quality/creativity)
  • Compatible with models trained with cfg_dropout_prob > 0
  • Files: src/fluxflow/utils/visualization.py