|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Build, Lint, and Test Commands |
| 6 | + |
| 7 | +```bash |
| 8 | +# Install in development mode |
| 9 | +pip install -e ".[dev]" |
| 10 | + |
| 11 | +# Run full test suite (requires beefy machine) |
| 12 | +make test |
| 13 | +# Or directly: |
| 14 | +python -m pytest -n auto --dist=loadfile -s -v ./tests/ |
| 15 | + |
| 16 | +# Run a single test file |
| 17 | +python -m pytest tests/<TEST_FILE>.py |
| 18 | + |
| 19 | +# Run slow tests (downloads many GBs of models) |
| 20 | +RUN_SLOW=yes python -m pytest -n auto --dist=loadfile -s -v ./tests/ |
| 21 | + |
| 22 | +# Format code (ruff + doc-builder) |
| 23 | +make style |
| 24 | + |
| 25 | +# Check code quality without modifying |
| 26 | +make quality |
| 27 | + |
| 28 | +# Fast fixup for modified files only (recommended before commits) |
| 29 | +make fixup |
| 30 | + |
| 31 | +# Fix copied code snippets and dummy objects |
| 32 | +make fix-copies |
| 33 | + |
| 34 | +# Check repository consistency (dummies, inits, repo structure) |
| 35 | +make repo-consistency |
| 36 | +``` |
| 37 | + |
| 38 | +## Code Architecture |
| 39 | + |
| 40 | +Diffusers is built on three core component types that work together: |
| 41 | + |
| 42 | +### Pipelines (`src/diffusers/pipelines/`) |
| 43 | +- End-to-end inference workflows combining models and schedulers |
| 44 | +- Base class: `DiffusionPipeline` (in `pipeline_utils.py`) |
| 45 | +- Follow **single-file policy**: each pipeline in its own directory |
| 46 | +- Loaded via `DiffusionPipeline.from_pretrained()` which reads `model_index.json` |
| 47 | +- Components registered via `register_modules()` become pipeline attributes |
| 48 | +- ~99 pipeline implementations (Stable Diffusion, SDXL, Flux, etc.) |
| 49 | + |
| 50 | +### Models (`src/diffusers/models/`) |
| 51 | +- Configurable neural network architectures extending PyTorch's Module |
| 52 | +- Base classes: `ModelMixin` + `ConfigMixin` (in `modeling_utils.py`) |
| 53 | +- **Do NOT follow single-file policy**: use shared building blocks (`attention.py`, `embeddings.py`, `resnet.py`) |
| 54 | +- Key subdirectories: |
| 55 | + - `autoencoders/`: VAEs for latent space compression |
| 56 | + - `unets/`: Diffusion model architectures (UNet2DConditionModel, etc.) |
| 57 | + - `transformers/`: Transformer-based models (Flux, SD3, etc.) |
| 58 | + - `controlnets/`: ControlNet variants |
| 59 | + |
| 60 | +### Schedulers (`src/diffusers/schedulers/`) |
| 61 | +- Guide denoising process during inference |
| 62 | +- Base class: `SchedulerMixin` + `ConfigMixin` (in `scheduling_utils.py`) |
| 63 | +- Follow **single-file policy**: one scheduler per file |
| 64 | +- Key methods: `set_num_inference_steps()`, `step()`, `timesteps` property |
| 65 | +- Easily swappable via `ConfigMixin.from_config()` |
| 66 | +- ~55 scheduler algorithms (DDPM, DDIM, Euler, DPM-Solver, etc.) |
| 67 | + |
| 68 | +### Supporting Systems |
| 69 | + |
| 70 | +- **Loaders** (`src/diffusers/loaders/`): Mixins for LoRA, IP-Adapter, textual inversion, single-file loading |
| 71 | +- **Quantizers** (`src/diffusers/quantizers/`): BitsAndBytes, GGUF, TorchAO, Quanto support |
| 72 | +- **Hooks** (`src/diffusers/hooks/`): Runtime optimizations (offloading, layer skipping, caching) |
| 73 | +- **Guiders** (`src/diffusers/guiders/`): Guidance algorithms (CFG, PAG, etc.) |
| 74 | + |
| 75 | +## Configuration System |
| 76 | + |
| 77 | +All components use `ConfigMixin` for serialization: |
| 78 | +- Constructor arguments stored via `register_to_config(**kwargs)` |
| 79 | +- Instantiate from config: `Component.from_config(config_dict)` |
| 80 | +- Save/load as JSON files |
| 81 | + |
| 82 | +## Key Design Principles |
| 83 | + |
| 84 | +1. **Usability over Performance**: Models load at float32/CPU by default |
| 85 | +2. **Simple over Easy**: Explicit > implicit; expose complexity rather than hide it |
| 86 | +3. **Single-file policy**: Pipelines and schedulers are self-contained; models share building blocks |
| 87 | +4. **Copy-paste over abstraction**: Prefer duplicated code over hasty abstractions for contributor-friendliness |
| 88 | + |
| 89 | +## Code Style |
| 90 | + |
| 91 | +- Uses `ruff` for linting and formatting (line length: 119) |
| 92 | +- Documentation follows [Google style](https://google.github.io/styleguide/pyguide.html) |
| 93 | +- Use `# Copied from` mechanism for sharing code between similar files |
| 94 | +- Avoid lambda functions and advanced PyTorch operators for readability |
| 95 | + |
| 96 | +## Testing |
| 97 | + |
| 98 | +- Tests use `pytest` with `pytest-xdist` for parallelization |
| 99 | +- Slow tests gated by `RUN_SLOW=yes` environment variable |
| 100 | +- Test dependencies: `pip install -e ".[test]"` |
0 commit comments