Bucko Model Merger v0.1 Beta 🧬

https://github.com/TheRealUncleBucky/Bucko-Model-Merger

Bucko Model Merger is a powerful visual workflow editor and advanced utility for merging machine learning models—specifically targeting diffusion models like Stable Diffusion (SD 1.5, SDXL), Flux, and Z-Image.

It provides fine-grained control over model interpolation, offering a suite of advanced merge modes, layer-specific block weights, and an intuitive Streamlit-based GUI to orchestrate complex merge pipelines.

✨ Key Features

• Intuitive Web Interface: Streamlit-based visual editor for configuring complex merging plans, tracking execution steps, and managing models.

• Advanced Merge Modes: Supports over 20 merging algorithms including Weighted Sum, DARE, CLIP XOR (XDARE), Add Difference, and Orthogonal Delta.

• Layer-Specific Block Weights: Combine the anatomy from one model with the shading/style of another using custom merge ratios for specific UNet/Transformer blocks.

• Extensive Architecture Support: Compatible with SD 1.5, SDXL, Flux, Z-Image, and Anima.

• LoRA Baking & Combining: Integrate LoRAs directly into checkpoint weights or combine multiple LoRAs.

• Direct Model Sourcing: Download checkpoints and LoRAs via direct URLs (CivitAI, HuggingFace) or use local paths.

• Workflow Automation: Save and load lightweight .txt plan files for perfect reproducibility and community sharing.

🚀 Getting Started

Prerequisites

• Python 3.10+

• Git

• Hardware: Sufficient RAM/VRAM or swap space is heavily recommended for large models (e.g., SDXL, Flux).

• (Optional) aria2: High-speed download utility (brew install aria2, sudo apt install aria2, or winget install aria2).

• (Optional) 4-bit source support: you can skip this unless you are merging a 4-bit quantized checkpoint. Dequantizing 4-bit quantized checkpoints requires the optional quant extra: pip install "bucko_model_merger[quant]".

Installation & Setup

1. Clone the repository

git clone https://github.com/TheRealUncleBucky/Bucko-Model-Merger.git
cd Bucko-Model-Merger

2. Set up a virtual environment and install requirements Using a virtual environment is highly recommended to isolate dependencies.

• macOS / Linux:

  python -m venv .venv
  source .venv/bin/activate
  pip install -r requirements.txt

• Windows:

  python -m venv .venv
  .venv\Scripts\activate
  pip install -r requirements.txt

3. Launch the application From a source checkout:

python -m streamlit run bucko_model_merger_app.py

If installed as a package:

bucko-model-merger

(Windows Users: If using the precompiled release, simply double-click Bucko.exe instead of doing steps 2 and 3. On your first launch, it will automatically create a local virtual environment and install the required dependencies — this downloads several GB of AI libraries (torch, diffusers, etc.) and typically takes 10–30 minutes on first launch, so keep the window open until it finishes.)

(macOS / Linux Users: there is no one-click launcher. After the one-time setup above, re-launch any time by activating your virtual environment and running python -m streamlit run bucko_model_merger_app.py.)

4. Verify the backend Once the app opens, navigate to the Settings tab and click 🔎 Check backend now to verify that torch, diffusers, and safetensors are configured correctly. If anything is missing, click 🛠 Install / repair backend dependencies.

⚙️ Configuration & API Keys

Navigate to the Settings tab within the application to configure:

• CivitAI API Token: Required to download most models directly via the CivitAI API.

• HuggingFace Token: Useful for interfacing with HuggingFace for private model downloads or uploads.

🧠 Supported Merge Modes

Bucko Model Merger goes far beyond simple averaging:

• Weighted Sum (WS): The baseline linear blend between two models.

• DARE: A stochastic delta merge using dropout/rescale techniques.

• Add Difference (AD): Transfers the difference between two models into a third base model.

• Orthogonal Delta (ORTHO): Adds only the orthogonal component of differences, protecting existing styles.

• Swap Components (SWAP): Directly swap complete modules (e.g., Text Encoder / CLIP or VAE) between models.

🔒 Steps Editor trust notes

Bucko now uses one method metadata contract for the UI, generated MMS plan text, and final backend command. Important behavior notes:

• DARE / XDARE: Beta is dropout probability. The backend drops delta values where rand < beta and rescales survivors by 1/(1-beta).

• Tensor Slice (TS): This is not a 3-model blend. Alpha controls slice length; beta controls slice offset; Model C is not used.

• Sparse Top-k (SPRSE): Deterministic top-k delta merge. It uses beta as the kept/top-k fraction and does not use seed or Model C.

• Frequency-Band (FREQ): Beta is the protected low-frequency cutoff. Higher beta protects more of Model A's broad structure.

• Guarded blocks: The Steps Editor protects prompt/text and fragile blocks such as BASE, IN00, and M00 unless Affect guarded blocks is enabled.

• Before/after diffs: Template apply, template mix, and bulk paste show exactly which block values changed after guarded-block protection is applied. A no-op warns loudly instead of looking successful.

• Trust check: Each selected merge step shows the method requirements, effective MMS line, and final backend command preview so the UI, plan text, and runtime command can be compared before running.

• SDXL block lists: Bucko edits 20 SDXL blocks. A pasted 21-value list drops the trailing backend VAE bucket; legacy 25/26-value SD1 block lists are rejected instead of guessed.

📝 Workflow Plan Files

The merger uses a custom .txt format to document and execute workflows automatically. Example BuckoModelMerger.txt:

+WAI, https://civarchive.com/models/827184/wai-illustrious-sdxl?modelVersionId=2883731, %CKPT
+COMIX, https://civarchive.com/models/2173364/comix?modelVersionId=2907004, %CKPT

CM WAI + COMIX 0,0,0.08,0.08,0.07,0.02,0.03,0.06,0.08,0.05,0,0.03,0.08,0.08,0.06,0.16,0.18,0.16,0.42,0.46 MERGE_1

1. +WAI and +COMIX register model aliases and source URLs.

2. CM (Checkpoint Merge) executes a block-weighted blend into a new output named MERGE_1.

🤝 Contributing

Contributions are welcome! Open an issue or submit a pull request if you have suggestions, feature requests, or bug reports.

⚠️ Disclaimer

Model merging can be extremely hardware-intensive. Ensure you have sufficient RAM/VRAM or swap space configured when running complex workflows on local hardware.

⚠️ Important beta note

This is not a magic “make perfect model” button.

It is more like a merging workbench / playground for people who want to experiment with model merging while dealing with fewer syntax goblins, fewer mystery settings, fewer accidental overwrites, and fewer crimes against their hard drive.

Please use backups.
Please test responsibly.
Please do not trust v0.1 Beta with your only copy of anything important.
That would be very brave, but also extremely cursed.

Also, full disclosure like before: although I do have a background in coding, I have used Claude Code and ChatGPT Codex heavily while building this. So again, I am not pretending this first beta is some flawless enterprise-grade machine from the heavens.