### Quick Start: Load and Analyze Image with Qwen3.5 VLM

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/docs/VLM-API.md

Demonstrates the initial setup to load the Qwen3.5 VLM, analyze an image with a prompt, and then unload the model. Ensure you have the FluxTextEncoders library imported.

```swift
import FluxTextEncoders

// Load VLM (auto-downloads if needed)
let downloader = TextEncoderModelDownloader()
let path = try await downloader.downloadQwen35(variant: .qwen35_4B_4bit)
try await FluxTextEncoders.shared.loadQwen35VLM(from: path.path)

// Analyze an image
let result = try FluxTextEncoders.shared.analyzeImageWithQwen35(
    image: myCGImage,
    prompt: "What do you see?"
)
print(result.text)

// Unload when done
await MainActor.run { FluxTextEncoders.shared.unloadQwen35VLM() }
```

--------------------------------

### Install Flux 2 App

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/README.md

Unzip the application bundle to install the Flux 2 App. Open the application to start using its features.

```bash
unzip Flux2App-v2.1.0-macOS.zip
open Flux2App.app
```

--------------------------------

### Quick Start LoRA Image-to-Image

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/docs/LoRA.md

Use this command to apply a LoRA adapter for image-to-image generation. Specify the input image, LoRA file path, scale, and model.

```bash
flux2 i2i "your prompt" \
  --images input.jpg \
  --lora path/to/lora.safetensors \
  --lora-scale 1.0 \
  --model klein-4b \
  -o output.png
```

--------------------------------

### Quick Start: Generate Image with Flux.2 Swift MLX

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/SKILL.md

Instantiate the Flux2Pipeline with a chosen model, load its models, and then generate an image from a text prompt. This example uses the Klein 4B model for fast generation.

```swift
import Flux2Core

// Create pipeline (Klein 4B for fast generation)
let pipeline = Flux2Pipeline(model: .klein4B)
try await pipeline.loadModels()

// Generate image
let image = try await pipeline.generateTextToImage(
    prompt: "a cat sitting on a chair",
    height: 1024,
    width: 1024,
    steps: 4,        // Klein uses 4 steps
    guidance: 1.0    // Klein uses guidance 1.0
)
```

--------------------------------

### Flux.2 CLI: Traditional I2I with Strength and Steps

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/docs/CLI.md

Example of a traditional image-to-image transformation using a prompt, a reference image, and specifying strength and effective denoising steps.

```bash
flux2 i2i "prompt" --steps 28 --strength 0.7
# Output: "Steps: 28 effective (total: 40)"
```

--------------------------------

### Configure and Start LoRA Training

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/SKILL.md

Sets up LoRA training parameters including dataset path, LoRA ranks, learning rate, and output path. Gradient checkpointing can be enabled to reduce memory usage.

```swift
import Flux2Core

// Configure training
let config = LoRATrainingConfig(
    datasetPath: URL(fileURLWithPath: "examples/cat-toy/train"),
    rank: 32,
    alpha: 32.0,
    learningRate: 1e-4,
    maxSteps: 250,
    batchSize: 1,
    resolution: 512,
    gradientCheckpointing: true,  // Reduces memory ~50%
    outputPath: URL(fileURLWithPath: "output/my-lora")
)

// Start training
let trainer = SimpleLoRATrainer(config: config, model: .klein4B)
try await trainer.train { step, loss, gradNorm in
    print("Step \(step): loss=\(loss), gradNorm=\(gradNorm)")
}
```

--------------------------------

### Train LoRA using Recommended Configuration

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/docs/examples/evaluate-lora/README.md

After evaluating a reference image, you can directly train a LoRA using the configuration file generated by the evaluation pipeline. This simplifies the training setup process.

```bash
flux2 train-lora --config my_eval/recommended_config.yaml
```

--------------------------------

### Complete Training Setup (end-to-end)

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/docs/VLM-API.md

Chains together the entire LoRA training process: reference photo analysis, VLM description, baseline evaluation, parameter recommendation, and YAML configuration generation. Includes VLM-supervised validation in the generated YAML.

```APIDOC
## Complete Training Setup (end-to-end)

Chains everything: reference photo → VLM describe → evaluate baseline → recommend → generate YAML.

```swift
let setupAPI = LoRATrainingSetup_API()
let setup = try await setupAPI.createEvaluatedTrainingConfig(
    referenceImagePath: "/path/to/photo.jpg",
    context: LoRAContext(name: "Vincent", description: "A specific person"),
    model: .klein4B,
    datasetPath: "./my_dataset",
    triggerWord: "VinZ"
) { progress in
    print(progress)
}

// The validation prompt was auto-generated from the reference photo
print(setup.validationPrompt)
// "VinZ, young man with short brown hair and rectangular black-rimmed glasses..."

// Export YAML with VLM scoring at every checkpoint
let yaml = setup.recommendation.toYAMLWithVLMScoring(
    model: .klein4B,
    triggerWord: "VinZ",
    validationPrompt: setup.validationPrompt,
    referenceImagePath: "/path/to/photo.jpg",
    checkpointEvery: 50
)
try yaml.write(toFile: "training_config.yaml", atomically: true, encoding: .utf8)
```

The generated YAML includes VLM-supervised validation:

```yaml
model:
  name: klein-4b
  quantization: bf16

lora:
  rank: 32
  alpha: 32.0

training:
  max_steps: 1000
  learning_rate: 0.0001

validation:
  prompts:
    - prompt: "VinZ, young man with short brown hair and glasses..."
      apply_trigger: false
      is_512: true
  every_n_steps: 50
  vlm_scoring:
    enabled: true
    reference_images:
      - /path/to/photo.jpg
    save_best_checkpoint: true
    compare_to_baseline: true
```
```

--------------------------------

### Install Flux 2 CLI

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/README.md

Use this command to unzip and run the Flux 2 Command Line Interface for text-to-image generation. Ensure you have the correct zip file for your version.

```bash
unzip Flux2CLI-v2.1.0-macOS.zip
./Flux2CLI t2i "a cat" --model klein-4b
```

--------------------------------

### Automatic Configuration Recommendation

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/SKILL.md

Uses the shared Flux2MemoryManager to get system RAM and recommend a suitable configuration for the pipeline. This is useful for automatically adapting to different hardware.

```swift
import Flux2Core

// Automatic recommendation based on system RAM
let memoryManager = Flux2MemoryManager.shared
print("System RAM: \(memoryManager.physicalMemoryGB) GB")

let recommended = memoryManager.recommendedConfig()
let pipeline = Flux2Pipeline(model: .klein9B, quantization: recommended)
```

--------------------------------

### Complete LoRA Training Setup

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/docs/VLM-API.md

Chains the entire LoRA training process from reference photo to YAML generation. It includes VLM evaluation and recommendation. The validation prompt is auto-generated.

```swift
let setupAPI = LoRATrainingSetup_API()
let setup = try await setupAPI.createEvaluatedTrainingConfig(
    referenceImagePath: "/path/to/photo.jpg",
    context: LoRAContext(name: "Vincent", description: "A specific person"),
    model: .klein4B,
    datasetPath: "./my_dataset",
    triggerWord: "VinZ"
) { progress in
    print(progress)
}

// The validation prompt was auto-generated from the reference photo
print(setup.validationPrompt)
// "VinZ, young man with short brown hair and rectangular black-rimmed glasses..."

// Export YAML with VLM scoring at every checkpoint
let yaml = setup.recommendation.toYAMLWithVLMScoring(
    model: .klein4B,
    triggerWord: "VinZ",
    validationPrompt: setup.validationPrompt,
    referenceImagePath: "/path/to/photo.jpg",
    checkpointEvery: 50
)
try yaml.write(toFile: "training_config.yaml", atomically: true, encoding: .utf8)
```

```yaml
model:
  name: klein-4b
  quantization: bf16

lora:
  rank: 32
  alpha: 32.0

training:
  max_steps: 1000
  learning_rate: 0.0001

validation:
  prompts:
    - prompt: "VinZ, young man with short brown hair and glasses..."
      apply_trigger: false
      is_512: true
  every_n_steps: 50
  vlm_scoring:
    enabled: true
    reference_images:
      - /path/to/photo.jpg
    save_best_checkpoint: true
    compare_to_baseline: true
```

--------------------------------

### Reduce Memory Usage with Quantization

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/docs/CLI.md

Apply more aggressive quantization settings to resolve out-of-memory errors during generation. This example uses 4-bit for text and qint8 for the transformer.

```bash
# Use more aggressive quantization
flux2 t2i "prompt" --text-quant 4bit --transformer-quant qint8
```

--------------------------------

### Early Stopping Example

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/docs/examples/vlm-scoring/README.md

Demonstrates how early stopping would function with a degradation threshold of 15, showing a scenario where training stops due to a significant score drop.

```text
Peak at step 75: 61/100
Step 100: 42/100 (dropped 19 points > 15 threshold)
Training would have stopped at step 100 with best checkpoint at step 75
```

--------------------------------

### Apply On-the-fly Quantization in Swift

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/docs/CustomModelIntegration.md

Apply on-the-fly quantization to the transformer model within the `loadTransformer` method. This example demonstrates quantizing to 8-bit or 4-bit integers, assuming bf16 weights are loaded.

```swift
// In Flux2Pipeline.loadTransformer():
if quantization.transformer == .qint8 {
    MLX.quantize(model: transformer!, groupSize: 64, bits: 8)
} else if quantization.transformer == .int4 {
    MLX.quantize(model: transformer!, groupSize: 64, bits: 4)
}
```

--------------------------------

### Flux.2 CLI: Style Transfer Example

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/docs/CLI.md

Applies a style transfer effect to an image using a text prompt, a reference image, specified strength, steps, and an output file name.

```bash
flux2 i2i "transform into a watercolor painting" \
  --images photo.jpg \
  --strength 0.7 \
  --steps 28 \
  --output watercolor.png
```

--------------------------------

### Compare Flux 2 Model Configurations

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/docs/examples/profiling.md

Use `flux2 profile compare` to benchmark multiple model and quantization configurations simultaneously. This is useful for identifying the most performant setup for a given prompt and image size.

```bash
# Compare Klein 4B quantizations
flux2 profile compare "a beaver building a dam" \
  --configs "klein-4b:qint8,klein-4b:bf16,klein-4b:int4"
```

```bash
# Compare models at same quantization
flux2 profile compare "a detailed landscape" \
  --configs "klein-4b:qint8,klein-9b:qint8" \
  --width 1024 --height 1024
```

```bash
# Multiple runs per config for more stable results
flux2 profile compare "a portrait photograph" \
  --configs "klein-4b:qint8,klein-4b:bf16" \
  --runs 3
```

--------------------------------

### Flux-2 Swift MLX Troubleshooting Snippets

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/SKILL.md

Code examples demonstrating how to address common issues like out-of-memory errors by adjusting quantization, enabling gradient checkpointing for training, or providing HuggingFace tokens for gated models.

```swift
// Out of memory → use more aggressive quantization
let pipeline = Flux2Pipeline(
    model: .klein4B,
    quantization: .ultraMinimal  // 4bit text + int4 transformer (~30GB)
)
```

```swift
// For training, enable gradient checkpointing to halve activation memory
let config = LoRATrainingConfig(
    datasetPath: datasetURL,
    gradientCheckpointing: true,  // Reduces memory ~50%, ~2x slower
    outputPath: outputURL
)
```

```swift
// Gated model access error → provide HuggingFace token
let pipeline = Flux2Pipeline(model: .dev, hfToken: "hf_xxxxx")
```

--------------------------------

### Multi-Image Conditioning: Beaver + Hat + Jacket

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/docs/examples/flux2-klein-9b/README.md

Combines elements from multiple reference images to generate a new image. This example uses multiple `--images` flags to specify visual references for the subject, hat, and jacket, along with a prompt that directs the model to use these references.

```bash
flux2 i2i "a beaver wearing the hat from image 2 and the jacket from image 3" \
  --model klein-9b \
  --images beaver_1024.png \
  --images hat.png \
  --images jacket.png \
  --steps 4 \
  -o beaver_hat_jacket.png
```

--------------------------------

### Run Klein 4B with int4 Quantization

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/docs/examples/quantization-benchmark/README.md

This command demonstrates how to run the Klein 4B model using int4 quantization, which is suitable for systems with 16 GB of RAM. Ensure you have the flux2 tool installed and the model downloaded.

```bash
flux2 t2i "your prompt" --model klein-4b --transformer-quant int4
```

--------------------------------

### Evaluate LoRA for a Unique Object (Cat Toy)

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/docs/examples/evaluate-lora/README.md

This example demonstrates evaluating a LoRA trained on a unique object, such as a hand-carved wooden cat figurine. Providing LoRA context helps the evaluation focus on specific details crucial for training.

```bash
flux2 evaluate-lora \
  --image examples/cat-toy/train/6.jpeg \
  --name "Cat Toy" \
  --lora-description "A specific hand-painted wooden cat figurine with colorful vertical stripes" \
  --model klein-4b
```

--------------------------------

### Flux-2 CLI: FLUX.2 Description

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/docs/VLM-API.md

Use the Flux-2 CLI to get a description of FLUX.2. Thinking is automatically disabled for this operation.

```bash
# FLUX.2 description (thinking disabled automatically)
flux2 test-qwen35 "Describe" --image photo.png --flux-describe
```

--------------------------------

### Image-to-Image Multi-Image Conditioning

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/SKILL.md

Generates a new image by combining elements or concepts from multiple input images, guided by a text prompt.

```APIDOC
## Image-to-Image Multi-Image Conditioning

### Description
Generates a new image by combining elements or concepts from multiple input images, guided by a text prompt.

### Method Signature
`generateImageToImage(prompt: String, images: [Image], steps: Int, guidance: Float) -> Image`

### Parameters
- **prompt** (String) - Required - The text description guiding the combination of image elements.
- **images** ([Image]) - Required - An array of images to condition the generation (up to 4 for Klein, 6 for Dev).
- **steps** (Int) - Required - The number of diffusion steps to perform.
- **guidance** (Float) - Required - The guidance scale for the generation process.

### Response
- **Image** - The generated image object.
```

--------------------------------

### Training Control via Files

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/docs/examples/TRAINING_GUIDE.md

Control training by creating specific files in the output directory. Use '.pause' to pause, '.checkpoint' for immediate checkpointing, and '.stop' to gracefully halt training.

```bash
# Pause training (saves checkpoint, waits)
touch output/cat-toy-lora/.pause
rm output/cat-toy-lora/.pause     # Resume

# Request immediate checkpoint + validation images
touch output/cat-toy-lora/.checkpoint

# Stop training gracefully (saves final checkpoint)
touch output/cat-toy-lora/.stop
```

--------------------------------

### VLM Analysis Excerpts

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/docs/examples/vlm-scoring/README.md

Examples of VLM feedback at different training stages, highlighting model learning, degradation, and the identification of the best checkpoint.

```text
Step 25 (14/100 — early training):
> Scene: "The generated image completely fails to match the reference. The subject is a different cat with different color scheme, pose, and facial expression."

Step 75 (61/100 — best checkpoint):
> Scene: "The generated image correctly identifies the subject as a painted wooden cat figurine with vertical stripes and a striped tail."
> Style: "The style is reasonably well-captured, including the hand-painted, rustic aesthetic and specific color palette."

Step 100 (42/100 — degradation):
> The VLM detected a quality drop. Without VLM scoring, the user would have used the final checkpoint (step 100) which is worse than step 75.
```

--------------------------------

### Describe Reference for Validation

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/docs/VLM-API.md

Generates a validation prompt from a reference photo, which is useful for manual training setup. This function requires the VLM to be loaded first.

```APIDOC
## Describe Reference for Validation

Generate a validation prompt from a reference photo. Useful when setting up training manually.

```swift
let setupAPI = LoRATrainingSetup_API()

// Load VLM first
try await FluxTextEncoders.shared.loadQwen35VLM(from: vlmPath)

let prompt = try setupAPI.describeReferenceForValidation(
    image: refImage,
    triggerWord: "VinZ"
)
// "VinZ, close-up portrait of a young man with short brown hair..."
```
```

--------------------------------

### On-the-fly Quantization with int4

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/README.md

Utilize int4 quantization for the Dev model to fit within 32 GB of memory. This offers significant memory savings.

```bash
# Dev with int4 (fits in 32 GB)
flux2 t2i "a cat" --model dev --transformer-quant int4
```

--------------------------------

### Initialize and Run Flux2OutpaintingChain

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/docs/examples/outpainting/README.md

Initialize the Flux2Pipeline and then the Flux2OutpaintingChain with image, padding, prompt, and seed. The chain handles the outpainting process internally.

```swift
import Flux2Core
import Flux2Chains

let pipeline = Flux2Pipeline(
    model: .klein9B,
    quantization: .memoryEfficient
)
try await pipeline.loadModels()

let chain = Flux2OutpaintingChain(
    pipeline: pipeline,
    image: inputCGImage,
    top: 0, bottom: 0,
    left: 480, right: 480,             // pixels to add per side
    prompt: "panoramic countryside, golden hour, lush hedge, gravel path",
    seed: 42
)
let result = try await chain.run()     // result.image: CGImage
```

--------------------------------

### Generate Image with Dev Model and Custom Steps

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/docs/examples/README.md

Use the `dev` model for maximum image quality. This requires at least 64GB of RAM and allows specifying the number of generation steps.

```bash
flux2 t2i "a cat wearing sunglasses" --model dev --steps 28
```

--------------------------------

### Display Flux-2 CLI Help

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/docs/examples/README.md

View all available options and commands for the Flux-2 CLI by running the help command.

```bash
flux2 --help
```

--------------------------------

### Build Flux2 CLI and Run Training

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/docs/examples/lion-vs-adamw/README.md

Build the Flux2 CLI and then run training for both AdamW and Lion configurations. Ensure the CLI is built before running the training commands.

```bash
# Build CLI first
xcodebuild -scheme Flux2CLI -configuration Release -destination 'platform=macOS' build

# Run both trainings
flux2 train-lora --config docs/examples/lion-vs-adamw/cat_toy_adamw.yaml
flux2 train-lora --config docs/examples/lion-vs-adamw/cat_toy_lion.yaml
```

--------------------------------

### Run Single Profiled Generation

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/docs/examples/profiling.md

Executes a single generation with profiling enabled. Use this to get a detailed trace of one inference run. Requires specifying the prompt and the model.

```bash
flux2 profile run "a beaver building a dam" --model klein-4b
```

--------------------------------

### Compare Quantization Configurations

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/docs/examples/profiling.md

Compares the performance of different model quantization configurations. Use this to evaluate the trade-offs between precision and speed. Specify the prompt and a comma-separated list of configurations.

```bash
flux2 profile compare "a beaver building a dam" \
  --configs "klein-4b:qint8,klein-4b:bf16"
```

--------------------------------

### Shape Mismatch Error Example

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/docs/LoRA.md

This error occurs when a LoRA is incompatible with the target model architecture. Ensure the `--model` argument matches the LoRA's intended model.

```text
MLX error: Shapes (6144,15360) and (3072,7680) cannot be broadcast
```

--------------------------------

### Run LoRA Training

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/docs/examples/tarot-style-lora/README.md

Execute the LoRA training process using a specified configuration file. Ensure you are in the repository root directory.

```bash
flux2 train-lora --config examples/tarot-style/tarot_training.yaml
```

--------------------------------

### Text-to-Image Generation with Higher Resolution

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/docs/examples/flux2-klein-9b/README.md

Generate images at higher resolutions by specifying width and height. This example uses landscape dimensions. Ensure the output filename is provided with -o.

```bash
flux2 t2i "a majestic eagle" \
  --model klein-9b \
  --width 1536 --height 1024 \
  -o eagle.png
```

--------------------------------

### Display System Information

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/docs/CLI.md

Use this command to view the system's hardware information, including RAM, and the status of available model quantization presets and loaded models.

```bash
flux2 info
```

--------------------------------

### VLM Scoring Configuration

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/docs/examples/vlm-scoring/README.md

Enable and configure VLM scoring within the training setup. This includes setting weights for different scoring components and deciding whether to compare against a baseline.

```yaml
vlm_scoring:
  enabled: true
  scene_weight: 0.5
  compare_to_baseline: true
  save_best_checkpoint: true
```

--------------------------------

### Describe Reference Image for Validation Prompt

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/docs/VLM-API.md

Generates a validation prompt from a reference photo using the VLM. This is useful for manual training setup. Ensure the VLM is loaded first.

```swift
let setupAPI = LoRATrainingSetup_API()

// Load VLM first
try await FluxTextEncoders.shared.loadQwen35VLM(from: vlmPath)

let prompt = try setupAPI.describeReferenceForValidation(
    image: refImage,
    triggerWord: "VinZ"
)
// "VinZ, close-up portrait of a young man with short brown hair..."
```

--------------------------------

### Run Dev 32B with int4 Quantization

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/docs/examples/quantization-benchmark/README.md

This command illustrates running the Dev 32B model using int4 quantization, making it accessible on systems with 32 GB of RAM or more. This is crucial for utilizing larger models on consumer hardware.

```bash
flux2 t2i "your prompt" --model dev --transformer-quant int4
```

--------------------------------

### Initialize and Run Flux2MaskedInpaintingChain

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/docs/examples/inpainting/README.md

Initializes the Flux2Pipeline and Flux2MaskedInpaintingChain, then runs the inpainting process. Ensure inputCGImage and maskCGImage are prepared beforehand.

```swift
import Flux2Core
import Flux2Chains

let pipeline = Flux2Pipeline(
    model: .klein9B,                   // distilled is fine, 4 steps
    quantization: .memoryEfficient
)
try await pipeline.loadModels()

let chain = Flux2MaskedInpaintingChain(
    pipeline: pipeline,
    prompt: "a vintage red Citroën 2CV in a sandy desert at golden hour",
    image: inputCGImage,
    mask: maskCGImage,                 // white = inpaint, black = keep
    steps: 4,
    guidance: 1.0,
    seed: 42
)
let result = try await chain.run()     // result.image: CGImage
```

--------------------------------

### Flux.2 CLI: Multi-Image Conditioning Command Structure

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/docs/CLI.md

Employ this command structure for multi-image conditioning, where two or three reference images guide the generation process. The strength parameter is ignored in this mode.

```bash
flux2 i2i <prompt> --images <img1> --images <img2> [--images <img3>] [options]
```

--------------------------------

### MemoryOptimizationConfig Presets for Denoising

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/SKILL.md

Shows how to configure memory optimization during denoising using predefined presets. These presets balance speed and memory efficiency.

```swift
import Flux2Core

// Presets (from fastest to most memory-efficient):
let light = MemoryOptimizationConfig.light           // Every 16 blocks
let moderate = MemoryOptimizationConfig.moderate      // Every 8 blocks (recommended)
let aggressive = MemoryOptimizationConfig.aggressive  // Every 4 blocks + cache clearing
let ultraLow = MemoryOptimizationConfig.ultraLowMemory // Every 2 blocks + cache clearing

let pipeline = Flux2Pipeline(
    model: .dev,
    quantization: .balanced,
    memoryOptimization: .aggressive
)
```

--------------------------------

### Run Klein 9B with qint8 Quantization

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/docs/examples/quantization-benchmark/README.md

This command shows how to run the Klein 9B model with qint8 quantization. This is useful as it now works correctly, whereas previously it might have fallen back to bf16. This configuration is beneficial for memory efficiency.

```bash
flux2 t2i "your prompt" --model klein-9b --transformer-quant qint8
```

--------------------------------

### Text-to-Image with Turbo LoRA Config

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/docs/LoRA.md

Generate images using text-to-image with a Turbo LoRA, leveraging a JSON configuration file for specialized settings. This example uses a custom LoRA configuration for advanced generation.

```bash
flux2 t2i "a beautiful landscape" \
  --lora-config turbo-lora.json \
  --model dev \
  -o output.png
```

--------------------------------

### Download Default Models

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/docs/CLI.md

Download the default models, including the qint8 transformer and VAE. This is the standard command for setting up Flux.

```bash
flux2 download
```

--------------------------------

### Train with Custom Model Directory

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/docs/CLI.md

Configure the training process to use models from a custom directory via the `--models-dir` flag.

```bash
# Training with custom directory
flux2 train-lora --config config.yaml --models-dir /path/to/my/models
```

--------------------------------

### Download and Load Flux 2 Models in Swift

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/SKILL.md

Models are automatically downloaded on first use. This Swift code demonstrates initializing a pipeline and tracking the download progress. It also shows how to check if specific models are already downloaded.

```swift
import Flux2Core

// Models are downloaded automatically on first use
let pipeline = Flux2Pipeline(model: .klein4B)
try await pipeline.loadModels { component, progress in
    print("Downloading \(component): \(Int(progress * 100))%")
}

// Check if models are available
let isAvailable = ModelRegistry.isDownloaded(.transformer(.klein4B_bf16))
```

--------------------------------

### Load Custom Text Encoder in Swift

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/docs/CustomModelIntegration.md

Update the `loadTextEncoder` function to specify how to load your custom model's text encoder. This example shows reusing an existing encoder variant like Klein's Qwen3-4B.

```swift
private func loadTextEncoder() async throws {
    switch model {
    case .myCustomModel:
        // Reuse Klein's Qwen3-4B encoder
        kleinEncoder = KleinTextEncoder(variant: .klein4B, quantization: qwen3Quant)
        try await kleinEncoder!.load()
    // ...
    }
}
```

--------------------------------

### Handling Out-of-Memory Scenarios

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/SKILL.md

Demonstrates strategies to mitigate Out-of-Memory errors, including using more aggressive quantization, memory optimization during denoising, reducing image resolution, and clearing GPU cache.

```swift
import Flux2Core

// Strategy 1: Use more aggressive quantization
let pipeline = Flux2Pipeline(
    model: .klein4B,
    quantization: .ultraMinimal  // 4bit text + int4 transformer
)

// Strategy 2: Use memory optimization during denoising
let pipeline = Flux2Pipeline(
    model: .klein9B,
    quantization: .balanced,
    memoryOptimization: .aggressive  // Periodic eval + cache clearing during denoising
)

// Strategy 3: Reduce image resolution (memory scales with pixel count)
let image = try await pipeline.generateTextToImage(
    prompt: "a landscape",
    height: 512,   // 4x less memory than 1024x1024
    width: 512,
    steps: 4,
    guidance: 1.0
)

// Strategy 4: Clear GPU cache between generations
pipeline.clearCacheEveryNSteps = 2  // More frequent cache clearing
await pipeline.clearAll()           // Full cleanup between generations
```

--------------------------------

### Tighter Memory Configuration for Klein 9B in Flux 2 Swift MLX

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/SKILL.md

Illustrates a memory-efficient configuration for Klein 9B using a 4-bit text encoder and a qint8 transformer. This setup is suitable for environments with tighter memory constraints.

```swift
// 4-bit text encoder + qint8 transformer for tighter memory
let tightConfig = Flux2QuantizationConfig(
    textEncoder: .mlx4bit,    // Qwen3-8B at 4-bit (~4 GB)
    transformer: .qint8       // Klein 9B at qint8 (~9.2 GB)
)

let pipeline = Flux2Pipeline(model: .klein9B, quantization: tightConfig)
try await pipeline.loadModels()
```

--------------------------------

### Quantization Comparison

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/docs/examples/profiling.md

Compare performance across different quantization configurations (bf16, qint8, int4) for the klein-4b model at a specified resolution. Results are saved to a specified output directory.

```bash
flux2 profile compare "a detailed portrait" \
  --configs "klein-4b:bf16,klein-4b:qint8,klein-4b:int4" \
  --width 1024 --height 1024 \
  --output-dir ./quant_comparison
```

--------------------------------

### Recommended Flux-2 Settings for LoRA

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/docs/LoRA.md

Provides recommended command-line arguments for using LoRA with Flux-2. Full precision transformer quantization and a LoRA scale between 1.0 and 1.1 are suggested.

```bash
--transformer-quant bf16  # Full precision recommended
--lora-scale 1.0-1.1      # Adjust based on LoRA
```

--------------------------------

### Evaluate LoRA Pipeline

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/docs/examples/README.md

Use this command to evaluate the gap between a reference image and the base model output before training a LoRA. It helps in getting recommended training parameters automatically. Outputs include a reference copy, baseline image, VLM prompt, comparison report, and a YAML training config.

```bash
flux2 evaluate-lora --image reference.png --model klein-4b --trigger-word "xyz_cat"
```

--------------------------------

### Benchmark with Warm-up

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/docs/examples/profiling.md

Performs statistical benchmarking of inference performance. Includes a warm-up run to ensure accurate measurements. Specify the prompt, model, number of warm-up runs, and total runs.

```bash
flux2 profile benchmark "a beaver building a dam" --model klein-4b --warmup 1 --runs 3
```

--------------------------------

### Multi-Image Conditioning for Image-to-Image

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/README.md

Combine multiple images and a text prompt for image-to-image generation, allowing for element conditioning.

```bash
# Multi-image conditioning (combine elements)
flux2 i2i "a cat wearing this jacket" \
  --images cat.jpg \
  --images jacket.jpg \
  --steps 28 \
  --output cat_jacket.png
```

--------------------------------

### Text-to-Image Generation with Performance Profiling

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/docs/examples/flux2-klein-9b/README.md

Profile the performance of the generation process by including the --profile flag. This is useful for identifying performance bottlenecks.

```bash
flux2 t2i "a beaver building a dam" \
  --model klein-9b \
  --profile \
  -o beaver.png
```

--------------------------------

### Initialize Flux2Pipeline with Custom Klein Encoder

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/docs/TextEncoders.md

Initializes the Flux2Pipeline using a local directory for the Klein text encoder, bypassing Hub downloads. This is useful for using uncensored or fine-tuned Qwen3 builds.

```swift
let encoderDir = URL(fileURLWithPath: "/path/to/qwen3-encoder")

let pipeline = Flux2Pipeline(
    model: .klein9B,
    quantization: .balanced,
    kleinEncoderPath: encoderDir
)
try await pipeline.loadModels()  // ← uses encoderDir, no Hub fetch
```

--------------------------------

### Image-to-Image with Multi-Image Conditioning

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/docs/examples/flux2-klein-9b/README.md

Combine elements from multiple images during image-to-image generation by listing them with the --images flag. This allows for complex compositions.

```bash
flux2 i2i "a beaver wearing the hat from image 2" \
  --model klein-9b \
  --images beaver.png \
  --images hat.png \
  -o beaver_with_hat.png
```

--------------------------------

### Flux-2 CLI: Pre-training Evaluation

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/docs/VLM-API.md

Conduct pre-training evaluation using the Flux-2 CLI. Specify reference image, model details, and output directory for the evaluation.

```bash
# Pre-training evaluation
flux2 evaluate-lora --image ref.png \
  --name "Vincent" \
  --lora-description "A specific person with glasses" \
  --model klein-4b --output-dir ./eval
```

--------------------------------

### Text-to-Image with Quantized Precision (qint8)

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/docs/examples/flux2-klein-4b/README.md

Generates an image using quantized precision (qint8), which is the default. Specify the output file name.

```bash
flux2 t2i "a beaver building a dam" \
  --model klein-4b \
  --transformer-quant qint8 \
  -o beaver_qint8.png
```

--------------------------------

### Download Small Decoder

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/docs/examples/small-decoder/README.md

Use these commands to download the small decoder variant. You can download the decoder only or the full model with the small decoder.

```bash
# Download small decoder only
flux2 download --vae-only --vae-variant small-decoder
```

```bash
# Download model + small decoder
flux2 download --model klein-4b --vae-variant small-decoder
```

--------------------------------

### Image Analysis with Custom Prompts and Options

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/docs/VLM-API.md

Perform free-form image analysis using a custom prompt, optional system prompt, and parameters like maxTokens and temperature. Set enableThinking to false for faster responses.

```swift
let result = try FluxTextEncoders.shared.analyzeImageWithQwen35(
    image: cgImage,
    prompt: "Describe the architecture in this photo",
    systemPrompt: "You are an architecture expert",  // optional
    enableThinking: false,  // skip reasoning, faster response
    maxTokens: 300,
    temperature: 0
)
```

--------------------------------

### VLM-Guided Checkpoint Selection Workflow

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/docs/examples/vlm-scoring/README.md

Illustrates the workflow for VLM-guided checkpoint selection during LoRA training. It highlights the new scoring step within the existing checkpoint saving process.

```text
Training Loop
  |
  +-- saveCheckpoint()
        +-- generateValidationImages()       (existing - generates images with LoRA)
              +-- scoreValidationImagesWithVLM()  (NEW - scores vs reference/baseline)
                    |-- Compare validation vs training reference (scene + style, 0-100)
                    |-- Compare validation vs baseline (step 0, no LoRA)
                    |-- Compute composite score
                    |-- Track best checkpoint -> best_checkpoint/
                    +-- Check early stopping (stagnation/degradation)
```

--------------------------------

### Download Models to Custom Directory

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/docs/CLI.md

Use the `--models-dir` flag with the `download` command to specify a custom location for storing downloaded models.

```bash
# Download models to a custom directory
flux2 download --models-dir /path/to/my/models
```

--------------------------------

### On-the-fly Quantization with qint8

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/README.md

Use qint8 quantization for the Klein 9B model to fit within 24 GB of memory. This allows for reduced memory usage without downloading separate model variants.

```bash
# Klein 9B with qint8 (fits in 24 GB)
flux2 t2i "a cat" --model klein-9b --transformer-quant qint8
```

--------------------------------

### Train LoRA using YAML Config

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/SKILL.md

Initiates LoRA training by referencing a YAML configuration file. This is a command-line interface command.

```bash
flux2 train-lora --config my_training.yaml
```

--------------------------------

### Load and Summarize Model Weights

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/docs/CustomModelIntegration.md

Load model weights from a directory and print their shapes to aid in deriving architecture parameters. This is useful when `config.json` is missing.

```swift
import MLX

// Load weights and inspect shapes
let weights = try Flux2WeightLoader.loadWeights(from: modelDirectoryURL)
Flux2WeightLoader.summarizeWeights(weights)

// This prints all key names and tensor shapes, for example:
// transformer_blocks.0.attn.to_q.weight: [3072, 15360]
// transformer_blocks.0.attn.to_k.weight: [3072, 15360]
// single_transformer_blocks.0.attn.to_qkv_mlp.weight: [15360, 3072]
```

--------------------------------

### Text-to-Image with Prompt Upsampling

Source: https://github.com/vincentgourbin/flux-2-swift-mlx/blob/main/SKILL.md

Generates an image and enhances the prompt using Mistral/Qwen3 models. Useful for richer image details based on a simpler prompt.

```swift
// Get both image and the enhanced prompt
let result = try await pipeline.generateTextToImageWithResult(
    prompt: "a sunset",
    upsamplePrompt: true  // Enhance with Mistral/Qwen3
)

print("Original: \(result.originalPrompt)")
print("Enhanced: \(result.usedPrompt)")
let image = result.image
```