Add Boogu-Image generation, editing, and turbo pipelines

[Boogu-Team]

What does this PR do?

Adds the Boogu-Image family of pipelines to diffusers:

• BooguImagePipeline — text-to-image generation and instruction-based image editing.
• BooguImageTurboPipeline — few-step DMD distilled generation.
• fp8 quantized inference examples for both, targeting the published fp8 checkpoints.

The integration is purely additive: it introduces new files only and does not modify any existing upstream module.

Published checkpoints (Hugging Face Hub, Boogu/…): Boogu-Image-0.1-Base, Boogu-Image-0.1-Edit, Boogu-Image-0.1-Turbo, and their -fp8 variants.

Pipelines & model

Component	File
Generation / edit pipeline	src/diffusers/pipelines/boogu/pipeline_boogu.py
Turbo (DMD few-step) pipeline	src/diffusers/pipelines/boogu/pipeline_boogu_turbo.py
Transformer backbone (model, attention module + processors, RoPE)	src/diffusers/models/transformers/transformer_boogu.py
Image processor	src/diffusers/pipelines/boogu/image_processor.py

Docs: docs/source/en/api/pipelines/boogu.md. Runnable examples: examples/boogu/ (base / edit / turbo + fp8, with README.md).

Convention compliance

Implemented against the repo's .ai rules:

• Single-file model. The transformer backbone, its attention module (BooguImageAttention) + stateless processors, and the RoPE helper all live in transformer_boogu.py (one model = one file).
• Attention. Routed through dispatch_attention_fn (no direct F.scaled_dot_product_attention in the forward path); attention masks always materialized as [B, 1, 1, L] bool to stay bit-exact with the trained checkpoints under the native bf16 backend. BooguImageAttention (modelled on Flux2Attention) holds the to_q/to_k/to_v/norm_q/norm_k/to_out layers and dispatches to a stateless processor.
• Inference-only. No weight-init (initialize_weights) — the model loads pretrained weights. __init__ follows the lazy convention.
• Turbo pipeline. BooguImageTurboPipeline is a standalone DiffusionPipeline (not a subclass of BooguImagePipeline), with shared methods carried via # Copied from and kept in sync by make fix-copies. Device placement / offloading / component registration reuse the DiffusionPipeline base class.
• Standard CFG. The pipeline exposes standard classifier-free guidance only. No dead code paths, no silent except Exception fallbacks, no unused "API-consistency" parameters — training / ablation / prompt-tuning code from the research repo was removed; only the inference path is integrated.

Verification

• All 6 examples/boogu/ scripts run end-to-end and produce correct images (base / edit / turbo + fp8).
• Every refactor verified against a pre-refactor reference. The base path (T2I + CFG, which exercises both attention processors) is bit-exact (maxdiff = 0) on GPU; the edit path (TI2I double-guidance) matches within that path's inherent GPU nondeterminism (~8–9e-2, confirmed equal to a same-code self-vs-self run). Checkpoints load strict (no missing/unexpected keys).
• CI gates pass locally: ruff check, ruff format --check, make fix-copies (no diff), check_dummies.
• Test suite under tests/pipelines/boogu/ and tests/models/transformers/test_models_transformer_boogu.py passes.

Notes for reviewers

• Double-stream attention & checkpoint keys. The single-stream attention processor is fully stateless. For the double-stream block, the per-stream projections (img_to_q / instruct_to_q / img_out / …) are stored in the already-published checkpoints under …img_instruct_attn.processor.*. Moving them onto BooguImageAttention to make that processor fully stateless would rename those state-dict keys and require re-saving the released Hub checkpoints. To keep existing downloads loading, those projections stay on the processor module for now; happy to do the key migration + re-publish in a follow-up if you prefer the fully-stateless form.
• Boosted Orthogonal Guidance (BOG) has been removed — it defaulted to off, so standard-CFG output is unchanged. We'd like to re-introduce it as its own guider class under src/diffusers/guiders/ (and route advanced features through modular diffusers) in a follow-up PR, keeping this one focused on the standard pipeline.
• TeaCache was removed from both the model and the pipeline; caching is deferred to CacheMixin / FirstBlockCache (and the WIP in Implement TeaCache  #12652).
• _keep_in_fp32_modules is intentionally not set: forcing time_caption_embed to fp32 changes bf16 inference numerics, so we left it to the model author / reviewer's call.
• The fp8 examples include a small DeepGEMM-disable shim with version branches that are load-bearing for transformers 5.10.x (the env var alone does not disable DeepGEMM there).

Required Hub-side checkpoint changes (no code change in this PR)

Important for reviewers: the published Boogu/Boogu-Image-0.1-* checkpoints on the Hub are still packaged for the old custom-remote-code loading path and will not load correctly against this PR's native diffusers classes until the Hub repos are updated. We will push these Hub-repo edits to land together with the PR. Diff below is Hub main → required state.

1. model_index.json — point component classes at diffusers, not the bundled remote-code modules.
On Hub main it currently is:

"scheduler":   ["scheduling_flow_match_euler_discrete_time_shifting", "FlowMatchEulerDiscreteScheduler"],
"transformer": ["transformer_boogu", "BooguImageTransformer2DModel"],

Both must become library refs so from_pretrained resolves the in-tree classes added by this PR:

"scheduler":   ["diffusers", "FlowMatchEulerDiscreteScheduler"],
"transformer": ["diffusers", "BooguImageTransformer2DModel"],

2. Delete the two remote-code shim modules (they are thin re-export stubs that import boogu … from the private research package and raise ModuleNotFoundError: boogu for any external user):

• transformer/transformer_boogu.py
• scheduler/scheduling_flow_match_euler_discrete_time_shifting.py

3. scheduler/scheduler_config.json — drop the legacy custom-scheduler keys. Hub main has:

{ "_class_name": "FlowMatchEulerDiscreteScheduler", "_diffusers_version": "0.33.1",
  "do_shift": true, "dynamic_time_shift": false, "time_shift_version": "v1",
  "seq_len": 4096, "num_train_timesteps": 1000 }

Remove do_shift, dynamic_time_shift, time_shift_version (these drove the old custom scheduler's time-shift; the official scheduler ignores them). Keep seq_len — the pipeline's time-shift adapter reads scheduler.config.seq_len to compute the shift mu, so it is load-bearing → final config keeps _class_name / _diffusers_version / seq_len / num_train_timesteps.

4. transformer/config.json — remove prompt_tuning_configs (the prompt-tuning subsystem was dropped from this integration; the key is otherwise ignored with a warning).

The same four edits apply to all six repos (Base, Edit, Turbo and their -fp8 variants). The mllm/, processor/, vae/ and weight files are unchanged.

---

Fixes # (issue)

Before submitting

• Did you use an AI agent (Claude Code, Codex, Cursor, etc.) to help with this PR? If so:
  • Did you read the Coding with AI agents guide?
  • Did you self-review the diff against .ai/review-rules.md?
• Did you read the contributor guideline?
• Did you read our philosophy doc? (important for complex PRs)
• Was this discussed/approved via a GitHub issue or the forum? Please add a link to it if that's the case.
• Did you make sure to update the documentation with your changes? Here are the
  documentation guidelines, and
  here are tips on formatting docstrings.
• Did you write any new necessary tests?
• Are you the author (or part of the team) of the model/pipeline (only applicable for model/pipeline related PRs)?

Who can review?

Anyone in the community is free to review the PR once the tests have passed. Feel free to tag
members/contributors who may be interested in your PR.

[yiyixuxu]

thanks a lot for the PR and the very thoughtful self-review :)
i left some comments/questions

[Boogu-Team]

thanks a lot for the PR and the very thoughtful self-review :)
i left some comments/questions

Thank you for the quick and thoughtful review, @yiyixuxu — much appreciated! 🙏

I've addressed all the comments and pushed the changes (commits 9e672c2, d202a23, 5cef903):

• single-file convention — merged the model's helper modules (rope /blocks / attention processors) into transformer_boogu.py.
• triton fused RMSNorm — removed; the published path always fell back to torch.nn.RMSNorm, so it's numerically identical.
• pipeline-subclass responsibilities — dropped all the custom device / offload / component-setter infrastructure from both pipelines; they now rely on DiffusionPipeline (.to() / _execution_device / enable_*_offload). This also made the previously-failing device/offload tests pass.

I've replied inline on each thread with the specifics and resolved them.
Happy to iterate further — thanks again!

[yiyixuxu]

thanks!
i left more comments

[Boogu-Team]

thanks! i left more comments

Thanks for the detailed second-round review! I've pushed updates addressing it — one commit per topic so each is easy to review in isolation:

Commit	What
05cc899ae	Drop all weight-init (initialize_weights), follow the lazy / inference-only __init__ convention
a597eed0b	Rename the Lumina-derived layers to BooguImage*
36298d3a6	Collapse the RoPE namespace class into a get_freqs_cis function (and drop the dead duplicate)
c9a6b5d06	Remove TeaCache (model + pipeline) and delete utils/teacache_util.py; defer caching to CacheMixin / FirstBlockCache
662e6ca11	Compute the time-shift mu via calculate_shift (# Copied from flux)
2977b2dce	Introduce BooguImageAttention (flux2-style) that holds the layers; processors dispatch through it
3b56e275c	Remove boosted-orthogonal-guidance; the pipeline now exposes standard CFG only

I've replied inline on each thread. Of the 20 comments, 18 are done; 2 I've left open with a question for you rather than guess:

1. retrieve_timesteps(..., sigmas=) (pipeline timesteps) — Boogu feeds the 0→1 sigma value directly as the timestep, whereas set_timesteps(sigmas=) forces timesteps = sigmas * num_train_timesteps + its own shift, which changes the numerics and breaks bit-exactness. I kept the explicit assignment for now and proposed a small scheduler flag as a clean alternative — would value your call on the thread.
2. Inlining img_patch_embed_and_refine into forward — happy to inline per the coding-style doc, just wanted to confirm the preference since forward is already large.

Two things I'd also like your steer on:

• Double-stream attention & checkpoint keys. The single-stream processor is now fully stateless. For the double-stream block, the per-stream projections (img_to_q / instruct_to_q / img_out / ...) are stored in the already-published checkpoints under ...img_instruct_attn.processor.*. Moving them onto BooguImageAttention to make that processor fully stateless would rename those state-dict keys and require re-saving the released Hub checkpoints (Base / Edit / Turbo / Turbo-fp8). To preserve compatibility for existing downloads, I kept those projections on the processor for this round. If you'd prefer the fully-stateless form, we'll do the key migration + re-publish in a follow-up once we can coordinate the Hub re-upload.
• Boosted Orthogonal Guidance. I removed it outright here (it defaulted to off, so standard CFG output is unchanged / bit-exact). I'd like to bring it back as its own guider class under src/diffusers/guiders/ — and route advanced features through modular diffusers — in a follow-up PR, keeping this one focused on the standard pipeline. Does that sequencing work for you?

Verification: every change is checked on GPU. The base path (T2I + CFG, which exercises both attention processors) is bit-exact (maxdiff=0) vs the pre-refactor reference; the edit path (TI2I double-guidance) matches within that path's inherent GPU nondeterminism (~8–9e-2, same as a same-code self-vs-self run). ruff check / ruff format / check_copies / check_dummies are clean, and the model + pipeline test suites pass. The six examples/boogu scripts (base / edit / turbo, each + fp8) all generate images correctly.

Thanks again — happy to iterate on the two open questions.