feat: add FLUX.3 Image Klein and Klein Base support

[leejet]

Summary

Add FLUX.3 Image Klein and Klein Base support.

Related Issue / Discussion

N/A

Additional Information

.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\flux-3-image-klein.safetensors --llm ..\models\text_encoders\Qwen3-VL-4B-Instruct-Q4_K_M.gguf --vae ..\models\vae\flux2_ae.safetensors -p "a lovely cat holding a sign says 'flux3.cpp'" --cfg-scale 1.0 --steps 16 --sampling-method euler -v --offload-to-cpu

.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\flux-3-image-klein-base.safetensors --llm ..\models\text_encoders\Qwen3-VL-4B-Instruct-Q4_K_M.gguf --vae ..\models\vae\flux2_ae.safetensors -p "a lovely cat holding a sign says 'flux3.cpp'" --cfg-scale 3.5 --steps 20 --sampling-method euler -v --offload-to-cpu

Checklist

• I have read and confirmed this PR follows the contribution guidelines.

Summary by CodeRabbit

• New Features
  • Added support for FLUX.3 Image Klein and Klein Base, including model detection, prompt handling, image generation, and reference-image editing.
  • Added usage instructions and examples for both models. Their default discrete scheduler uses a flow shift of 6.93, which can be overridden with --flow-shift.
  • Added FLUX.3 to the supported image-model list.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: 79368a79-182c-46ff-97e6-6ea5ef173ce6

📥 Commits

Reviewing files that changed from the base of the PR and between e47426c and 6d6ff75.

⛔ Files ignored due to path filters: 3

• assets/flux3/flux3-image-klein-base.png is excluded by !**/*.png
• assets/flux3/flux3-image-klein-edit.png is excluded by !**/*.png
• assets/flux3/flux3-image-klein.png is excluded by !**/*.png

📒 Files selected for processing: 12

• README.md
• docs/edit.md
• docs/flux3.md
• src/conditioning/conditioner.hpp
• src/model.h
• src/model/diffusion/flux3.hpp
• src/model/diffusion/model.hpp
• src/model/te/llm.hpp
• src/model_loader.cpp
• src/pipeline/diffusion_engine.cpp
• src/pipeline/model_builders.cpp
• src/runtime/denoiser.hpp

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 9 remain after this review.

📝 Walkthrough

The pull request adds FLUX.3 Image Klein and Klein Base support, including model detection, prompt conditioning, diffusion execution, scheduler behavior, and usage documentation.

Changes: FLUX.3 Image Klein support

Layer / File(s)	Summary
Model recognition and prompt conditioning src/model.h, src/model_loader.cpp, src/conditioning/conditioner.hpp, src/model/te/llm.hpp	The model version and loader recognize FLUX.3. Its prompt path selects QWEN3_VL, pads token sequences to multiples of 80, and passes custom position IDs to LLMRunner.
Flux3 diffusion runner and wiring src/model/diffusion/model.hpp, src/model/diffusion/flux3.hpp, src/pipeline/model_builders.cpp	The new runner processes image, reference-image, and text streams. The model builder constructs the Flux3 conditioner and runner. Diffusion parameters can carry a target timestep.
Sampling and documented usage src/runtime/denoiser.hpp, src/pipeline/diffusion_engine.cpp, README.md, docs/edit.md, docs/flux3.md	Flux3 sampling uses a dedicated flow denoiser and passes target timesteps to the runner. The documentation lists model sources, generation and editing examples, and the default flow shift of 6.93.

Priority: ⬇️ Low

Estimated code review effort: 4 (Complex) | ~60 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant ModelLoader
  participant build_core_runners
  participant LLMEmbedder
  participant LLMRunner
  participant diffusion_engine
  participant Flux3FlowDenoiser
  participant Flux3Runner
  ModelLoader->>build_core_runners: identifies VERSION_FLUX3
  build_core_runners->>LLMEmbedder: creates Flux3 conditioner
  LLMEmbedder->>LLMRunner: passes position_ids
  diffusion_engine->>Flux3FlowDenoiser: requests Flux3 sigmas
  diffusion_engine->>Flux3Runner: passes target_timestep

Loading

Suggested reviewers: fszontagh

Merge Risk: ⚪ Minimal · up to 6d6ff

The reported crashes are not reachable through the supported FLUX.3 paths; no identified issue needs resolution before merging.

Security architecture risk: 🔵 Low · up to 6d6ff

The new inference path has no demonstrated increase in access or privileges. Input-compatibility assumptions and incomplete integration coverage leave some uncertainty.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — The demonstrated exposure is the inference process and its backend allocations when callers select the new model path. The inspected changes do not establish additional service, tenant, credential, or environment authority; deployment-level exposure remains unspecified.

Trust Boundaries and Controls

• inferred — Model weights influence dimensions, block counts, and allocations. The new runner has limited explicit cross-model shape validation, but standard prompt and image producers constrain runtime inputs. This extends the existing local model-file trust pattern; the inspected evidence does not demonstrate a newly attacker-reachable boundary bypass or memory-corruption outcome.

Resilience and Maintainability Implications

• inferred — Repeated serialized execution preserves the common runner's cleanup and ownership behavior. Concurrent use of one runner remains an inherited unsupported assumption, rather than an established regression introduced by this PR.

Pre-merge checks: 4 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 31 functions across 9 files. (3 skipped: 3…	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks: 4 passed

Check name	Status	Explanation
Title check		The title clearly and concisely describes the main change: adding FLUX.3 Image Klein and Klein Base support.
Description check		The description includes all required template sections. It states the change, marks related discussion as not applicable, provides verification commands and output images, and confirms the contributi…
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 31 functions across 9 files. (3 skipped: 3 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches: 💡 1

📝 Generate docstrings: 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Warning

Some tools did not complete. Review the errors below.

🔧 Cppcheck (2.22.0)

src/pipeline/diffusion_engine.cpp

Cppcheck timed out; analysis of this file is incomplete

src/pipeline/model_builders.cpp

Cppcheck timed out; analysis of this file is incomplete

_{Comment @coderabbitai help to get the list of available commands.}