Contributing¶
The most useful contribution is a new model. The bar is the one every existing model met: it must reproduce the reference implementation, and the evidence has to be in the repository.
Setup¶
uv venv -p 3.13 .venv && uv pip install --python .venv -e ".[dev,image,docs]"
.venv/bin/python scripts/fetch_fixtures.py
.venv/bin/python -m pytest
.venv/bin/mkdocs serve # preview this site
Set HF_TOKEN when your accepted repository licenses grant access to gated fixtures. Restricted
files are verified against tests/fixtures/RESTRICTED.json and remain in the ignored
tests/fixtures/_restricted cache.
Adding a model¶
- Open an issue naming the model, its repository and its weight license. One issue per model keeps review focused.
- Download the real configs first and keep them as test fixtures
(
tests/fixtures/<model>_configs/). Write components against the configs that were actually published, not against assumptions. - Implement the components in
imagehub/models/(and schedulers inimagehub/schedulers/, tokenizers inimagehub/tokenization_*.py) as plain PyTorch. Share a component with an existing family only when it is genuinely the same code. - Add the backend in
imagehub/backends/: aTextToImageBackendthat validates options before loading, loads lazily, and returns anImageResultwhose metadata records the run. Register it inimagehub/registry.py. - Add the catalog entry in
imagehub/catalog.py: model id, pinned 40-character revision, file list, license, provenance, and thecatalog_idthat links to awesome-text-to-image-architectures. - Prove parity with reference tests under
tests/reference/: strict load, each component, then an end-to-end generation from the same noise on CPU in float32. They are skipped unlessIMAGEHUB_REFERENCE_TESTS=1and never download anything. Tests that import the authors' code find its checkout withreference_source("<name>")fromtests/reference_sources.py, which readsIMAGEHUB_REFERENCE_SOURCES(defaultcheckpoints/ref-src). - Record the result in
docs/validation.json(withscripts/build_validation.py) anddocs/validation.md, add the model todocs/models.mdanddocs/catalog.md, and to the table in the README. A changed page that has a Turkish version is updated in both languages; see Translations. - Open a pull request against
main, one model per PR, closing its issue.
What a models.md section needs
A level-1 heading with the architecture name, then the line
Catalog: [...] · Models: \id`, ... · Task: `t2i``, then Architecture, Usage,
Settings, Seed compatibility, Out of scope and License paragraphs. The site builds
the family page, the model grid and the navigation from this file and the catalog, so there is
nothing else to edit.
What the docs site builds from¶
Nothing on this site repeats a fact by hand.
| Page | Source |
|---|---|
| Landing counts and model grid | imagehub/catalog.py, docs/validation.json |
| Family pages | docs/models.md split by catalog family |
| Results | docs/validation.json |
| Gallery | docs/assets/gallery/*.json and the image pairs beside them |
| Catalog, Validation record | docs/catalog.md, docs/validation.md |
The generator is scripts/docs_hooks.py; it runs inside mkdocs serve and mkdocs build.
mkdocs build --strict must pass.
Adding a gallery pair¶
Put <model-id>.reference.webp, <model-id>.imagehub.webp and <model-id>.json (name, family,
settings, max_pixel_diff) into docs/assets/gallery/. The pair appears on the gallery page and on the
model's own page.
Translating¶
English pages are the source. A translation is a sibling file with the locale before the extension,
for example quickstart.tr.md next to quickstart.md. Pages without a translation fall back to
English, so a language can grow page by page.
Style¶
Code is formatted with ruff (line length 100) and type-checked with mypy. Documentation is plain and specific: state what was measured, on what, and what is not claimed.