██████╗  █████╗ ████████╗ █████╗ ██████╗ ██╗   ██╗██╗██╗     ██████╗ ███████╗██████╗
██╔══██╗██╔══██╗╚══██╔══╝██╔══██╗██╔══██╗██║   ██║██║██║     ██╔══██╗██╔════╝██╔══██╗
██║  ██║███████║   ██║   ███████║██████╔╝██║   ██║██║██║     ██║  ██║█████╗  ██████╔╝
██║  ██║██╔══██║   ██║   ██╔══██║██╔══██╗██║   ██║██║██║     ██║  ██║██╔══╝  ██╔══██╗
██████╔╝██║  ██║   ██║   ██║  ██║██████╔╝╚██████╔╝██║███████╗██████╔╝███████╗██║  ██║
╚═════╝ ╚═╝  ╚═╝   ╚═╝   ╚═╝  ╚═╝╚═════╝  ╚═════╝ ╚═╝╚══════╝╚═════╝ ╚══════╝╚═╝  ╚═╝

---

DataBuilder is a desktop application covering the full text-to-image training pipeline: dataset preparation, tag management, LoRA and full fine-tune training, image generation, and model/LoRA library management. Built with PyQt6, targeting RTX 4090 / H100 class hardware, with backends for 16 model architectures including Flux, SD3.5, and HiDream.

Why DataBuilder? Most trainers force you to juggle separate tools for dataset prep, training, and generation. DataBuilder bundles them into one native desktop UI. Speed is a primary goal — we ship with torch.compile integration, custom Triton kernels, optional FP8 training (Ada/Hopper), memory-mapped datasets, and the Marmotte optimizer (10-20× less optimizer memory than AdamW). Whether DataBuilder is the fastest at any given task depends on the model and hardware; the project is honest about being a work in progress on that front.

---

Screenshots

Screenshots coming soon — contributions welcome!

---

Features

Dataset Management

• Tag-based sorting — 80 rarity buckets using numpy percentile quantiles; rare concepts get up to 20× more repeats automatically
• Visual image browser — Navigate images with per-image bucket control and LRU pixmap cache
• Caption tools — Tag shuffle/dropout simulation, token count analysis, spell check, semantic grouping
• Tag histogram — Frequency distribution with top/rare/distribution views
• Duplicate detection — Exact (MD5) and near-duplicate (perceptual hash) detection
• Bulk operations — Rename, merge, search & replace tags; full undo/redo (Ctrl+Z)
• One-click pipeline — Automated clean + train workflow for beginners

Training

• 16 model architectures — See full table below
• 14 optimizers — Including the custom Marmotte optimizer (10-20× less optimizer state memory than AdamW)
• 7 training presets — Character LoRA, Style LoRA, Concept LoRA, Photorealistic, Quick Test, DPO, ControlNet
• ControlNet training — 9 conditioning types (canny, depth, pose, segmentation, normal, MLSD, softedge, scribble, inpaint)
• DPO training — Direct Preference Optimization with sigmoid, hinge, and IPO loss
• Real-time monitoring — Live loss curves, LR schedule preview, VRAM usage bar, sample preview
• Mid-training controls — Save Now, Sample Now, Backup Project, Pause/Resume, Stop
• Smart resume — Analyzes loss curves and auto-adjusts LR/optimizer on resume
• SpeeD (CVPR 2025) — Asymmetric timestep sampling + change-aware loss weighting

Speed optimizations (The Marmotte Philosophy)

Speed is a primary goal after correctness. The optimizations below are integrated and configurable from the UI; the speedup and memory columns are the published or commonly-cited ranges for the underlying technique, not validated DataBuilder benchmarks. Real-world numbers depend heavily on model, GPU, and config — please benchmark on your own hardware before relying on a specific number.

UI & UX

• Dark/light theme — Ctrl+T, persisted across sessions
• Drag & drop — Drop folders onto any input
• Keyboard shortcuts — Ctrl+S, Ctrl+O, Ctrl+E, Ctrl+R, Ctrl+T, Ctrl+D, Ctrl+Z
• Tooltips — Detailed explanations on every parameter
• Toast notifications — Non-blocking status messages
• Virtual tag table — O(1) rendering, handles 1M+ tags

Generation & Library

• Integrated generator — Text-to-image and img2img with LoRA support
• Batch generation — Prompt queue, CSV/JSON/TXT import, auto-save
• A/B comparison — Side-by-side generation with per-side overrides
• Model merging — Weighted sum, SLERP, add-difference
• LoRA library — Favorites, notes, tags, ratings

---

Supported Architectures

Distilled variants (Lightning, LCM, Hyper-SD, Turbo, Flux Schnell, DMD/DMD2) are auto-detected by filename and routed to CFG=1.0 with low step counts.

All backends support both diffusers directories and single-file .safetensors / .ckpt checkpoints.

---

Quick Start

Requirements

Installation

git clone https://github.com/marmotte5/DataBuilder-.git
cd DataBuilder-

One-click install — no Python required

The installer downloads its own Python. You don't need Homebrew, you don't need to install Python yourself, you don't need admin rights.

After install, you get a proper app icon to launch:

• macOS — DataBuilder.app lives next to the project files. Drag it to your Applications folder or Dock for permanent access.
• Windows — a DataBuilder shortcut with the app icon is dropped on your Desktop automatically by the installer.

The installer uses uv (Astral's Rust-based Python installer) under the hood. On first run it:

1. Bootstraps uv to ~/.local/bin/uv if it's not already installed.
2. Downloads a hermetic Python 3.12 build (no system-Python needed).
3. Creates .venv/, picks the right extra for your hardware (.[mac] on macOS, .[cuda] on Linux+NVIDIA, .[all] otherwise), and installs everything.

First-time macOS double-click: Gatekeeper may block unsigned .command files with a "could not be opened" warning. Right-click the file → Open → confirm. After that first time, double-clicks work normally.

Or one command in a terminal

./install.sh    # macOS / Linux — uses uv automatically
install.bat     # Windows — uses uv automatically

The installer auto-detects your platform, finds a supported Python, verifies it can build a working venv (catching the broken Homebrew Python issue early on macOS), creates .venv/, and installs the right dependency set:

Once it finishes:

source .venv/bin/activate     # macOS / Linux
# .venv\Scripts\activate      # Windows
python -m dataset_sorter

Manual install

git clone https://github.com/marmotte5/DataBuilder-.git
cd DataBuilder-

# Use a 3.10 – 3.13 interpreter explicitly to avoid Python 3.14 footguns.
python3.12 -m venv .venv
source .venv/bin/activate     # Linux / macOS
# .venv\Scripts\activate      # Windows
pip install --upgrade pip

# Pick the extra that matches your machine:
pip install ".[mac]"          # macOS — Apple Silicon or Intel
pip install ".[cuda]"         # Linux + NVIDIA GPU
pip install ".[all]"          # Other (Windows, Linux without NVIDIA, …)
pip install ".[training]"     # Minimal — UI + core ML stack only

python -m dataset_sorter

The pyproject extras carry environment markers, so .[all] no longer detonates on macOS — pip simply skips the CUDA-only wheels (flash-attn, triton, liger-kernel, bitsandbytes, …).

Linux system dependencies

On headless Linux or minimal installations:

sudo apt-get install libegl1 libgl1

macOS / Apple Silicon

Tested on M1, M1 Pro/Max, M2, M3 series. Training runs on the MPS backend.

Hardware requirements

Prerequisites

# 1. Install Xcode Command Line Tools (required for compilers)
xcode-select --install

# 2. Install Python 3.12 (3.13 also works). Choose ONE of these two:

# (a) Official python.org installer — recommended, avoids the broken
#     pyexpat that some Homebrew python@3.12 builds ship with:
#     https://www.python.org/downloads/release/python-31210/
#     Download the macOS 64-bit universal2 .pkg and run it.

# (b) Homebrew (try first; if you hit a "_XML_SetAllocTrackerActivationThreshold"
#     error during venv creation, fall back to (a)):
brew install python@3.12

Installation

git clone https://github.com/marmotte5/DataBuilder-.git
cd DataBuilder-

# The installer picks `.[mac]` automatically — no CUDA-only deps fetched.
./install.sh

source .venv/bin/activate
python -m dataset_sorter

If you'd rather do it manually:

python3.12 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install ".[mac]"          # curated extra — Apple-Silicon-friendly only
python -m dataset_sorter

Known MPS limitations

• FP16 training is not stable on MPS — DataBuilder automatically falls back to BF16/FP32.
• flash-attn, triton, and transformer-engine are CUDA-only; skip the [speed] and [all] extras.
• bitsandbytes has limited MPS support; 8-bit/4-bit quantised optimizers will not be available.
• num_workers > 0 in the DataLoader can cause hangs on macOS — DataBuilder sets num_workers=0 automatically when MPS is detected.
• torch.compile requires triton (not available on MPS) and is automatically disabled.
• FP32 training can trigger MPS OOM on the first forward pass — DataBuilder automatically sets PYTORCH_MPS_HIGH_WATERMARK_RATIO=0.0 at startup to disable the memory ceiling and let the Metal allocator use all available unified memory. You can override this by setting the env var yourself before launching.

---

Your First LoRA in 5 Steps

For a detailed step-by-step tutorial, see docs/QUICKSTART.md.

TL;DR:

1. Scan your image dataset (drag & drop the folder)
2. Review tags — delete noise, merge duplicates, adjust buckets
3. Export project (Ctrl+E) — creates the structured training folder
4. Pick a preset — "Character LoRA" or "Style LoRA" are great starting points
5. Start Training — monitor live loss, save samples at any step

---

Project Folder Structure

my_project/
├── project.json                   # Project metadata
├── dataset/                       # Exported & organized dataset
│   ├── 1_1_common/                # 1× repeat (most common tags)
│   ├── 5_10_medium/               # 5× repeat
│   └── 20_40_rare_concept/        # 20× repeat (rarest tags)
├── models/                        # Final trained weights
├── samples/                       # Sample images generated during training
├── checkpoints/                   # Step/epoch checkpoints
├── backups/                       # Timestamped full project backups
├── logs/                          # Training logs + TensorBoard events
└── .cache/                        # Latent & text encoder caches

---

Architecture Overview

dataset_sorter/
├── __main__.py              # Entry point
├── models.py                # TrainingConfig dataclass, ImageEntry, DatasetStats
├── constants.py             # Model types, optimizers, presets
├── trainer.py               # Core training engine
├── training_worker.py       # QThread training worker
├── generate_worker.py       # QThread generation worker
├── backend_registry.py      # Auto-discovery of model backends
├── train_backend_base.py    # Base class for backends
├── train_backend_*.py       # 17 model backends
├── optimizers.py            # Marmotte, SOAP, Muon optimizers
├── triton_kernels.py        # Triton fused kernels
├── fp8_training.py          # FP8 training (2× TFLOPS)
├── sequence_packing.py      # Zero padding waste
├── mmap_dataset.py          # Memory-mapped datasets
├── zero_bottleneck_dataloader.py  # GIL-free dataloader
└── ui/
    ├── main_window.py       # Main window orchestrator
    ├── training_tab.py      # Training UI (180+ parameters, 7 tabs)
    ├── generate_tab.py      # Generation tab
    ├── library_tab.py       # LoRA & model library
    ├── batch_generation_tab.py  # Batch generation
    ├── comparison_tab.py    # A/B comparison
    └── model_merge_tab.py   # Model merging

---

Contributing

We welcome contributions! Whether you want to add a new model backend, improve an optimizer, fix a bug, or improve documentation — you're in the right place.

See CONTRIBUTING.md for guidelines on:

• Setting up your dev environment
• Adding a new model backend (it's designed to be easy!)
• Code style and conventions
• Submitting pull requests

---

License

MIT License — see LICENSE for details.

Free to use, modify, and distribute. Commercial use allowed. No warranty.

---