Metadata-Version: 2.5
Name: imagehub
Version: 0.1.0
Summary: Open-weight image generation architectures, natively reimplemented in PyTorch with parity evidence
Project-URL: Homepage, https://github.com/gorkemgul/imagehub
Project-URL: Repository, https://github.com/gorkemgul/imagehub
Project-URL: Documentation, https://gorkemgul.github.io/imagehub/
Project-URL: Changelog, https://github.com/gorkemgul/imagehub/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/gorkemgul/imagehub/issues
Author: gorkemgul
License-Expression: Apache-2.0 AND LicenseRef-NVIDIA-NSCLv1
License-File: LICENSE
License-File: NOTICE
License-File: THIRD_PARTY_NOTICES.md
License-File: licenses/BK-SDM-CreativeML-OpenRAIL-M.txt
License-File: licenses/Diffusers-Apache-2.0.txt
License-File: licenses/ETRI-KOALA-Dual-License.txt
License-File: licenses/HART-MIT.txt
License-File: licenses/HiDream-O1-MIT.txt
License-File: licenses/Ideogram4-Apache-2.0.txt
License-File: licenses/Infinity-MIT.txt
License-File: licenses/LlamaGen-MIT.txt
License-File: licenses/Lumina-DiMOO-Apache-2.0.txt
License-File: licenses/Meissonic-Apache-2.0.txt
License-File: licenses/OpenAI-CLIP-MIT.txt
License-File: licenses/PixelDiT-NSCLv1.txt
License-File: licenses/SDXS-Apache-2.0.txt
License-File: licenses/Segmind-SSD-1B-Apache-2.0.txt
License-File: licenses/Segmind-distill-sd-CreativeML-OpenRAIL-M.txt
License-File: licenses/Show-o-Apache-2.0.txt
License-File: licenses/Transformers-Apache-2.0.txt
License-File: licenses/bagel/LICENSE
License-File: licenses/bagel/SOURCE.json
License-File: licenses/emu3/LICENSE
License-File: licenses/emu3/SOURCE.json
License-File: licenses/hart/LICENSE
License-File: licenses/hart/SOURCE.json
License-File: licenses/hidream-o1/LICENSE
License-File: licenses/hidream-o1/SOURCE.json
License-File: licenses/ideogram4/LICENSE
License-File: licenses/ideogram4/SOURCE.json
License-File: licenses/infinity/LICENSE
License-File: licenses/infinity/SOURCE.json
License-File: licenses/llamagen/LICENSE
License-File: licenses/llamagen/SOURCE.json
License-File: licenses/lumina-dimoo/LICENSE
License-File: licenses/lumina-dimoo/SOURCE.json
License-File: licenses/meissonic/LICENSE
License-File: licenses/meissonic/SOURCE.json
License-File: licenses/nextstep/LICENSE
License-File: licenses/nextstep/SOURCE.json
License-File: licenses/pixeldit/LICENSE
License-File: licenses/pixeldit/NOTICE
License-File: licenses/pixeldit/SOURCE.json
License-File: licenses/show-o/LICENSE
License-File: licenses/show-o/SOURCE.json
Keywords: artificial-intelligence,diffusion,image-generation,pytorch
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Requires-Dist: torch>=2.2
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: mypy>=1.13; extra == 'dev'
Requires-Dist: pytest-cov>=5; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.9; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material==9.7.7; extra == 'docs'
Requires-Dist: mkdocs-static-i18n==1.3.1; extra == 'docs'
Requires-Dist: mkdocs==1.6.1; extra == 'docs'
Provides-Extra: image
Requires-Dist: pillow>=10; extra == 'image'
Provides-Extra: reference
Requires-Dist: diffusers==0.40.0; extra == 'reference'
Requires-Dist: peft==0.21.2; extra == 'reference'
Requires-Dist: protobuf; extra == 'reference'
Requires-Dist: scipy; extra == 'reference'
Requires-Dist: sentencepiece; extra == 'reference'
Requires-Dist: torchvision; extra == 'reference'
Requires-Dist: transformers==5.18.0; extra == 'reference'
Provides-Extra: training
Requires-Dist: pillow>=10; extra == 'training'
Description-Content-Type: text/markdown

<p align="center">
  <picture>
    <source media="(max-width: 600px)" srcset="https://raw.githubusercontent.com/gorkemgul/imagehub/main/docs/assets/banner-mobile.svg" />
    <img src="https://raw.githubusercontent.com/gorkemgul/imagehub/main/docs/assets/banner.svg" alt="imagehub — one API for open text-to-image models. The input &quot;a photograph of an astronaut riding a horse&quot; passes through a small neural network, and the output switches between images from different open models." width="100%" />
  </picture>
</p>

<h2 align="center">Open-weight text-to-image architectures in native PyTorch.</h2>

imagehub provides one API for open-weight text-to-image architectures using native PyTorch reimplementations; PyTorch is the only required runtime dependency. CPU float32 outputs are bit-identical to the reference implementations; see [validation](https://github.com/gorkemgul/imagehub/blob/main/docs/validation.md). It supports Python 3.11 and later.

## Install

```bash
pip install imagehub            # torch only
pip install "imagehub[image]"   # adds Pillow for Image.to_pil()
```

## Quickstart

```bash
python -m imagehub.pretrained sd-v1-5 checkpoints/sd-v1-5
```

```python
from imagehub import pipeline

with pipeline("t2i", backend="sd-v1-5", model="checkpoints/sd-v1-5") as pipe:
    result = pipe("a photograph of an astronaut riding a horse", seed=42)
result.images[0].save("astronaut.png")
print(result.metadata)
```

Most models accept text alone. Some also accept an optional `image=` input for image-conditioned generation or editing.

```python
from PIL import Image
with pipeline("t2i", backend="flux1-kontext-dev", model="checkpoints/flux1-kontext-dev") as edit:
    result = edit("Add a red hat to the scene", image=Image.open("photo.png"), seed=0)
result.images[0].save("edited.png")
```

LoRA adapters load on the Stable Diffusion 1.x and 2.x, SDXL, SD3, FLUX.1, FLUX.2 klein, Sana,
Qwen-Image, Z-Image, Lumina 2, HiDream-I1, Krea 2 and Ideogram 4 backends
([details](https://github.com/gorkemgul/imagehub/blob/main/docs/models.md#lora-adapters)):

```python
with pipeline("t2i", backend="sd-v1-5", model="checkpoints/sd-v1-5",
              lora="style.safetensors", lora_scale=0.8) as pipe:
    result = pipe("a watercolor fox", seed=0)
```

## Train

```bash
pip install "imagehub[training]"
```

```python
from imagehub.training import ImageFolderDataset, Trainer, TrainingArguments

trainer = Trainer(
    model="sd-v1-5",
    checkpoint="checkpoints/sd-v1-5",
    args=TrainingArguments(output_dir="runs/my-dog", max_steps=1000),
    train_dataset=ImageFolderDataset("my_images"),  # images + metadata.jsonl
)
trainer.train()
trainer.save_model("runs/my-dog/final")  # load it back with lora=".../adapter.safetensors"
```

LoRA training covers Stable Diffusion 1.x and 2.x, SDXL and its fine-tunes, SD3 and 3.5, FLUX.1,
FLUX.2 klein, Sana, Qwen-Image, Z-Image, Lumina 2, HiDream-I1 and Krea 2. The
[training guide](https://github.com/gorkemgul/imagehub/blob/main/docs/guides/training.md) lists every trainable checkpoint.

## Models

The [model catalog](https://github.com/gorkemgul/imagehub/blob/main/docs/catalog.md) lists every supported checkpoint with its source, pinned revision, and license.
Creating a pipeline for a checkpoint without commercial-use rights emits an `ImageHubLicenseWarning`, which standard Python warning filters can silence. The former `ImagehubLicenseWarning` spelling remains an alias.

<details>
<summary>All model families</summary>

| Family | Checkpoints | Task | Input | Validation |
| --- | --- | --- | --- | --- |
| Latent Diffusion Model | `ldm-text2im-large-256` | `t2i` | T | CPU fp32 parity |
| Stable Diffusion | `sd-v1-1`, `sd-v1-2`, `sd-v1-3`, `sd-v1-4`, `sd-v1-5`, `dreamshaper-8`, `segmind-small-sd`, `segmind-tiny-sd`, `bk-sdm-base`, `bk-sdm-small`, `bk-sdm-tiny`, `bk-sdm-v2-base`, `bk-sdm-v2-small`, `bk-sdm-v2-tiny`, `sd-v2-1`, `sd-turbo`, `sdxs-512-0.9`, `lcm-dreamshaper-v7` | `t2i` | T | CPU fp32 parity (`segmind-tiny-sd` on the upcast float16 weights) |
| Stable Diffusion XL | `sdxl-base-1.0`, `sdxl-lightning-2step`, `sdxl-lightning-4step`, `sdxl-lightning-8step`, `hyper-sdxl-1step`, `dmd2-sdxl-4step`, `dmd2-sdxl-1step`, `sdxl-turbo`, `ssd-1b`, `segmind-vega`, `koala-700m`, `koala-1b`, `koala-lightning-700m`, `koala-lightning-1b`, `playground-v2`, `playground-v2.5`, `juggernaut-xl-v9`, `animagine-xl-4.0`, `dreamshaper-xl-1.0` | `t2i` | T | CPU fp32 parity (Juggernaut and Animagine on upcast float16 weights) |
| Stable Diffusion XL refiner | `sdxl-refiner-1.0` | `t2i` | T, I | CPU fp32 parity |
| Stable Diffusion 3 and 3.5 | `sd3-medium`, `sd3.5-medium`, `sd3.5-large`, `sd3.5-large-turbo` | `t2i` | T | CPU fp32 parity |
| DreamLite | `dreamlite-base`, `dreamlite-mobile` | `t2i` | T, I | CPU fp32 parity on the upcast bfloat16 weights |
| JoyAI-Image | `joyai-image-edit`, `joyai-image-edit-plus` | `t2i` | T, I | CPU fp32 parity on the upcast bfloat16 weights |
| Cosmos-Predict2 | `cosmos-predict2-2b-t2i` | `t2i` | T | CPU fp32 parity on the upcast bfloat16 weights |
| FLUX.1 | `flux1-schnell`, `flux1-dev`, `flux1-krea-dev`, `flux-1-lite-8b` | `t2i` | T | CPU fp32 parity on the upcast bfloat16 weights |
| FLUX.1 Kontext | `flux1-kontext-dev` | `t2i` | T, I | CPU fp32 parity |
| VisualCloze | `visualcloze-384` | `t2i` | T, I | CPU fp32 parity |
| FLUX.2 | `flux2-klein-4b`, `flux2-klein-9b` | `t2i` | T | CPU fp32 parity |
| HunyuanDiT | `hunyuan-dit-v1.1-distilled`, `hunyuan-dit-v1.2`, `hunyuan-dit-v1.2-distilled` | `t2i` | T | CPU fp32 parity |
| DeepFloyd IF | `deepfloyd-if-i-xl` | `t2i` | T | CPU fp32 parity |
| Kandinsky 2.1 | `kandinsky-2-1` | `t2i` | T | CPU fp32 parity |
| Kandinsky 2.2 | `kandinsky-2.2` | `t2i` | T | CPU fp32 parity |
| Kandinsky 3 | `kandinsky-3` | `t2i` | T | CPU fp32 parity on the upcast float16 weights |
| Kandinsky 5 | `kandinsky-5-t2i-lite` | `t2i` | T | CPU fp32 parity |
| Stable Cascade | `stable-cascade`, `stable-cascade-lite` | `t2i` | T | CPU fp32 parity |
| Würstchen v2 | `wuerstchen-v2` | `t2i` | T | CPU fp32 parity |
| PixArt | `pixart-sigma-xl-1024`, `pixart-sigma-xl-512`, `pixart-sigma-xl-256`, `pixart-sigma-xl-2k`, `pixart-alpha-xl-1024`, `pixart-alpha-xl-512`, `pixart-lcm-xl-1024` | `t2i` | T | CPU fp32 parity |
| Sana | `sana-1600m-1024`, `sana-600m-1024`, `sana-sprint-1.6b-1024`, `sana-1.5-4.8b-1024` | `t2i` | T | CPU fp32 parity |
| Kolors | `kolors` | `t2i` | T | CPU fp32 parity on the upcast float16 weights |
| Lumina-Image 2.0 | `lumina-image-2.0` | `t2i` | T | CPU fp32 parity |
| Lumina-Next | `lumina-next` | `t2i` | T | CPU fp32 parity |
| Lumina-DiMOO | `lumina-dimoo` | `t2i` | T | CPU fp32 parity on the upcast bfloat16 weights |
| OmniGen | `omnigen-v1` | `t2i` | T, I | CPU fp32 parity on the upcast bfloat16 transformer |
| Ovis-Image | `ovis-image-7b` | `t2i` | T | CPU fp32 parity on the upcast bfloat16 VAE weights |
| aMUSEd | `amused-256`, `amused-512` | `t2i` | T | CPU fp32 parity |
| Meissonic | `meissonic` | `t2i` | T | CPU fp32 parity |
| AuraFlow | `auraflow-v0.3` | `t2i` | T | CPU fp32 parity |
| PRX | `prx-1024-t2i-beta`, `prx-512-t2i-sft` | `t2i` | T | CPU fp32 parity on the upcast bfloat16 text encoder |
| Chroma | `chroma1-hd`, `chroma1-flash`, `chroma1-base` | `t2i` | T | CPU fp32 parity on the upcast bfloat16 weights |
| LlamaGen | `llamagen-t2i-xl-256`, `llamagen-t2i-xl-512` | `t2i` | T | CPU fp32 parity |
| Infinity | `infinity-2b` | `t2i` | T | CPU fp32 parity; 256px shortened validation run |
| HART | `hart` | `t2i` | T | CPU fp32 parity on the upcast bfloat16 text encoder |
| Show-o | `show-o-512` | `t2i` | T | CPU fp32 parity |
| Emu3 | `emu3-gen` | `t2i` | T | CPU fp32 parity with shortened 24×16 end-to-end runs |
| NextStep-1 | `nextstep-1-large` | `t2i` | T | CPU fp32 parity on the upcast bfloat16 weights |
| PixelDiT | `pixeldit` | `t2i` | T | CPU fp32 parity; code is NSCLv1, non-commercial |
| Krea 2 | `krea2-turbo` | `t2i` | T | CPU fp32 parity |
| Nucleus-Image | `nucleus-image` | `t2i` | T | CPU fp32 parity on the upcast bfloat16 weights |
| ERNIE-Image | `ernie-image` | `t2i` | T | CPU fp32 parity without the prompt enhancer |
| LongCat-Image | `longcat-image` | `t2i` | T | CPU fp32 parity |
| HunyuanImage 2.1 | `hunyuanimage-2-1` | `t2i` | T | CPU fp32 parity |
| CogView3-Plus | `cogview3-plus-3b` | `t2i` | T | CPU fp32 parity on the upcast bfloat16 transformer and VAE |
| CogView4 | `cogview4-6b` | `t2i` | T | CPU fp32 parity |
| GLM-Image | `glm-image` | `t2i` | T | CPU fp32 parity |
| Ideogram 4 | `ideogram4-fp8` | `t2i` | T | CPU fp32 parity with the official implementation |
| Qwen-Image | `qwen-image`, `qwen-image-2.1` | `t2i` | T | CPU fp32 parity on the upcast bfloat16 weights |
| Qwen-Image-Edit | `qwen-image-edit`, `qwen-image-edit-2509` | `t2i` | T+I | CPU fp32 parity on the upcast bfloat16 weights, shortened 32×32 end-to-end runs |
| Z-Image | `z-image`, `z-image-turbo` | `t2i` | T | CPU fp32 parity |
| Janus-Pro | `janus-pro-1b`, `janus-pro-7b` | `t2i` | T | CPU fp32 parity |
| BAGEL | `bagel-7b-mot` | `t2i` | T | CPU fp32 parity on the upcast bfloat16 weights |
| HiDream-I1 | `hidream-i1-dev`, `hidream-i1-fast`, `hidream-i1-full` | `t2i` | T | CPU fp32 parity on the upcast bfloat16 and float16 weights |
| HiDream-O1 | `hidream-o1-image` | `t2i` | T | CPU fp32 parity |

</details>

## Validation

Every listed checkpoint is validated against its reference implementation, with CPU float32 image outputs required to match bit-for-bit. The [validation documentation](https://github.com/gorkemgul/imagehub/blob/main/docs/validation.md) describes the coverage and recorded results.

## Documentation

[Documentation site](https://gorkemgul.github.io/imagehub/) · [Model catalog](https://github.com/gorkemgul/imagehub/blob/main/docs/catalog.md) · [Model architecture notes](https://github.com/gorkemgul/imagehub/blob/main/docs/models.md) · [Validation](https://github.com/gorkemgul/imagehub/blob/main/docs/validation.md) · [Changelog](https://github.com/gorkemgul/imagehub/blob/main/CHANGELOG.md) · [Third-party notices](https://github.com/gorkemgul/imagehub/blob/main/THIRD_PARTY_NOTICES.md)

## Development

```bash
uv venv -p 3.13 .venv && uv pip install --python .venv -e ".[dev,image]"
.venv/bin/python scripts/fetch_fixtures.py
.venv/bin/python -m pytest
```

Some published configuration and tokenizer fixtures retain checkpoint-specific license terms and
are fetched into the ignored `tests/fixtures/_restricted` cache. Set `HF_TOKEN` before running the
fetcher to include gated repositories; tests for unavailable fixtures skip with the same command.

Reference comparisons are optional; install `.[dev,image,reference]` and run `IMAGEHUB_REFERENCE_TESTS=1 .venv/bin/python -m pytest tests/reference` with local checkpoint paths configured.
A few of them import the authors' original code; point `IMAGEHUB_REFERENCE_SOURCES` at a folder of
those checkouts (default `checkpoints/ref-src`), and the tests skip when a checkout is missing.

The documentation site builds with the pinned versions in the `docs` extra:

```bash
uv pip install --python .venv -e ".[docs]"
.venv/bin/mkdocs build --strict
```

## License

The project is Apache-2.0 overall. Clearly marked third-party derivatives retain their own license;
in particular, the PixelDiT source is NSCLv1 and non-commercial. Each checkpoint also has its own
license; see the [model catalog](https://github.com/gorkemgul/imagehub/blob/main/docs/catalog.md), [NOTICE](https://github.com/gorkemgul/imagehub/blob/main/NOTICE), and
[third-party notices](https://github.com/gorkemgul/imagehub/blob/main/THIRD_PARTY_NOTICES.md).

## Roadmap

Planned work after the first release:

- [x] LoRA adapter loading for inference — #193
- [x] Training support: LoRA fine-tuning as `imagehub[training]` — #194
- [ ] GPU and half-precision validation — #195
- [ ] More model families — #11
