Files

8.4 KiB

Development & Contribution

Everything for working on TheNoise itself: installing from a git clone, running the test suite, building the portable release bundles, and contributing.

End users should follow Setup instead — the released portable bundles need none of this.

Repository layout

thenoise/                  the package
  models/                  per-model adapters (detect + DEFAULT_PREFS + sampling)
  dit/                     per-model DiT code (lumina — the shared S3-DiT core behind
                           zimage and ming_image; krea2, qwen_image, qwen_image21,
                           anima, flux2, flux3, mage_flow, moss_image)
  vae/                     VAE loaders (Qwen-Image, Flux, Flux.2, Wan 2.2, Mage)
  samplers/                denoising solvers (`SAMPLERS` is the list `/health` reports)
  upscale/                 latent + pixel upscalers
  controlmap/              control-map extractors (canny, lineart, softedge, depth, pose)
  postprocess/             grain, sharpening, Qwen-VAE enhance
  ui/                      web UI served by `serve`
  mediums.py               per-medium controllers and routes (`image`, `video`, …)
  api.py / cli.py          HTTP API and CLI entry points
scripts/                   download.py — the unified model download helper
build-scripts/             portable bundle build, archive, GPU qualification
docker/                    container image, entrypoint, Compose example
tests/                     test suite (runs without real weights)

Setup from source

1. Install uv

uv is the only prerequisite - it provides the Python interpreter and installs every dependency:

curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.bashrc

2. Clone the repo

git clone https://github.com/lemonade-sdk/thenoise.git
cd thenoise

3. Bootstrap the environment

thenoise.sh creates the .venv, installs the ROCm build of PyTorch, and installs the project in editable mode. Running it with --help does all of that without needing any model weights yet:

./thenoise.sh --help

This is the slow step - it downloads several GB of ROCm PyTorch wheels. Subsequent runs skip the torch install (detected via import torch).

By default the script autodetects the GPU's architecture. Override with the GFX_ARCH environment variable if needed:

GFX_ARCH=gfx1151 ./thenoise.sh --help

4. Download a model

Model downloads use huggingface_hub, which lives in the scripts extra (thenoise.sh only installs runtime deps). Install it once, then use the venv's Python (a bare system python will not work):

uv pip install -e ".[scripts]"
.venv/bin/python scripts/download.py --model anima

All models and options: see the model pages or scripts/download.py --help.

5. Generate an image

./thenoise.sh generate \
  --dit ./models/anima/split_files/diffusion_models/anima-turbo-v1.0.safetensors \
  --vae ./models/anima/split_files/vae/qwen_image_vae.safetensors \
  --text-encoder ./models/anima/split_files/text_encoders/qwen_3_06b_base.safetensors \
  --prompt "a fox walking in the snow" \
  --out fox.png

The first generation is slow because the DiT is compiled with torch.compile — see First run.

6. Dev extras

thenoise.sh installs the runtime dependencies only. To run the test suite, install the dev extras:

uv pip install -e ".[dev]"

To use the model download helper, install the scripts extra (or in addition):

uv pip install -e ".[scripts]"

Never run uv sync. It would replace/break the ROCm torch build that thenoise.sh installs directly into the venv. torch is intentionally not listed in pyproject.toml. Use uv pip install for anything else.

Running the tests

The test suite is designed to run without real model weights:

.venv/bin/python -m pytest tests/ -q

Run this before pushing or opening a PR.

Building the portable bundles

CI (build-thenoise-rocm.yml) publishes the portable release bundles per GPU target. Locally:

bash build-scripts/build_portable.sh gfx1151          # assemble the bundle
bash build-scripts/create_portable_archive.sh         # package it as release tar.gz(es)
bash build-scripts/qualify_thenoise.sh --root <bundle> --model-dir <dir>   # GPU smoke test

build_portable.sh produces a relocatable directory (standalone CPython, ROCm PyTorch, all deps, bundled clang, bin/thenoise launcher, plus scripts/download.py + huggingface-hub for model downloads). create_portable_archive.sh splits it into ≤1.9 GB parts when needed (GitHub's asset limit). qualify_thenoise.sh runs on a real GPU: import checks, model download, one end-to-end generation including the first-run torch.compile.

Building the container image

docker/Dockerfile builds the bundle with the same build_portable.sh and copies it onto a bare Ubuntu, so the image and the portable bundle cannot drift apart. Locally:

docker build -f docker/Dockerfile --build-arg GFX_ARCH=gfx1151 -t thenoise:local .
docker compose -f docker/docker-compose.yml up -d anima

build-docker-image.yml publishes one image per GPU target to GHCR on every v* tag — a release is the only thing that moves the rolling gfx<target> tag the docs point at, while a manual run publishes as edge-gfx<target> beside it. A pull request builds nothing until a reviewer applies the docker-build label: that is how you get a change to the image, the bundle scripts or the package checked before merging. What CI can check without a GPU is the launcher coming up and import torch resolving every library the wheels expect; the real generation is manual, on whatever hardware you have.

Keep them in sync when changing the bundle: ensure_soname_symlinks and the bundled clang are what let the container run with no ROCm and no compiler installed, and the image's runtime stage carries the only system libraries the wheels do not vendor (libgomp1, libatomic1).

Contributing

PRs are welcome - especially new model support. A model addition typically touches:

  1. thenoise/models/<name>.py — the adapter: SIGNATURE (the tensor names that make a checkpoint this model's), DEFAULT_PREFS, CAPABILITIES, sampling loop. Derive it from PixelModel when the model renders images or clips; a medium that renders neither derives from DiffusionModel and says which medium it is (MEDIUM), along with any checkpoint the CLI should stop requiring (REQUIRED_COMPONENTS)
  2. thenoise/dit/<name>/ — model weights layout, loading, tokenizer configs. Put the Signature next to the loader that reads the geometry, and start that read with header.require(SIGNATURE): the catalog and the loader then agree on one claim, so a file cannot be selected by a loader that cannot build it. Nothing below dit/ opens a checkpoint header itself — it is handed a Header, parsed once per checkpoint for the whole load (read_header is the only place a file is opened), and renames it with relabel when the module tree spells a leaf differently.
  3. scripts/download.py — a ModelSpec entry + artifact registry for the Hugging Face files
  4. docs/models/<name>.md — presentation, specs, examples, download and usage instructions
  5. tests/ — detection/loading tests that run without real weights
  6. pyproject.toml — the new thenoise.dit.<name> package (if any)

General rules:

  • Keep the one-model-at-a-time, explicit-flags design - no hidden config, no workflow layer.
  • Anything a request/checkpoint/model can set goes through the request → checkpoint marker → model default preference chain (DiffusionModel.pref).
  • Weights land on a module through load_module_state, never a bare load_state_dict: a checkpoint that does not line up gets both halves of the difference named, instead of a forward pass that answers with plausible nonsense. A codec loads one level up, through load_codec, which adds the signature, the geometry read off the same header and the checkpoint's own key layout.
  • Don't add torch to pyproject.toml.
  • Verify with .venv/bin/python -m pytest tests/ -q before opening the PR.