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 ROCmtorchbuild thatthenoise.shinstalls directly into the venv.torchis intentionally not listed inpyproject.toml. Useuv pip installfor 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:
thenoise/models/<name>.py— the adapter:SIGNATURE(the tensor names that make a checkpoint this model's),DEFAULT_PREFS,CAPABILITIES, sampling loop. Derive it fromPixelModelwhen the model renders images or clips; a medium that renders neither derives fromDiffusionModeland says which medium it is (MEDIUM), along with any checkpoint the CLI should stop requiring (REQUIRED_COMPONENTS)thenoise/dit/<name>/— model weights layout, loading, tokenizer configs. Put theSignaturenext to the loader that reads the geometry, and start that read withheader.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 belowdit/opens a checkpoint header itself — it is handed aHeader, parsed once per checkpoint for the whole load (read_headeris the only place a file is opened), and renames it withrelabelwhen the module tree spells a leaf differently.scripts/download.py— aModelSpecentry + artifact registry for the Hugging Face filesdocs/models/<name>.md— presentation, specs, examples, download and usage instructionstests/— detection/loading tests that run without real weightspyproject.toml— the newthenoise.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 defaultpreference chain (DiffusionModel.pref). - Weights land on a module through
load_module_state, never a bareload_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, throughload_codec, which adds the signature, the geometry read off the same header and the checkpoint's own key layout. - Don't add
torchtopyproject.toml. - Verify with
.venv/bin/python -m pytest tests/ -qbefore opening the PR.