Skip to content

docs: correct stated defaults in Chroma pipeline docstrings - #14578

Open
iridescentWen wants to merge 2 commits into
huggingface:mainfrom
iridescentWen:docs/chroma-docstring-defaults
Open

docs: correct stated defaults in Chroma pipeline docstrings#14578
iridescentWen wants to merge 2 commits into
huggingface:mainfrom
iridescentWen:docs/chroma-docstring-defaults

Conversation

@iridescentWen

Copy link
Copy Markdown
Contributor

Third docs PR after #14345 and #14541 (both merged).

What's wrong

The three Chroma pipelines' __call__ docstrings state defaults to X for seven parameters where
the signature uses a different value. Anyone who reads the docstring and passes the documented number
explicitly gets different behavior than omitting the argument — which is the opposite of what a
stated default is for.

Every value below was read from the corresponding __call__ signature via AST, not inferred:

File __call__ Parameter Docstring said Signature
pipeline_chroma.py :589 num_inference_steps 50 35
pipeline_chroma.py :589 guidance_scale 3.5 5.0
pipeline_chroma_img2img.py :648 guidance_scale 3.5 5.0
pipeline_chroma_inpainting.py :766 num_inference_steps 35 28
pipeline_chroma_inpainting.py :766 guidance_scale 3.5 7.0
pipeline_chroma_inpainting.py :766 strength 0.9 0.6
pipeline_chroma_inpainting.py :766 max_sequence_length 512 256

The pattern looks like the docstrings were carried between the three pipelines (and from a Flux-style
ancestor) while the signatures were retuned per pipeline. Note the internal evidence that
defaults to really is meant to mirror the literal signature default here: in the same
pipeline_chroma.py docstring, num_images_per_prompt (defaults to 1) and
max_sequence_length (defaults to 512) both match their signature exactly — only these seven drifted.

Docstrings only, no behavior change.

Correct ones left alone

Not everything the scan surfaced was wrong, and I did not touch what already agrees:
pipeline_chroma_img2img.py's num_inference_steps (35) and strength (0.9) both match, as does
max_sequence_length (512) in pipeline_chroma.py and pipeline_chroma_img2img.py.

How I found it, and one thing I got wrong on the way

An AST pass comparing each documented defaults to <literal> against the signature's actual literal
default. It reports only when both sides are comparable literals, and deliberately skips two classes
that are not defects: a None signature default whose docstring names the value resolved in the
body (intentional), and prose defaults like "defaults to the model's current device".

Worth flagging because it nearly produced a wrong entry above: my first pass used a file-wide grep for
max_sequence_length: and picked up encode_prompt's signature (= 512) instead of __call__'s
(= 256), which would have made the inpainting row look correct. The table is built from
per-function AST lookups for that reason.

Validation

$ uvx ruff check src/diffusers/pipelines/chroma/
All checks passed!

$ uvx ruff format --check src/diffusers/pipelines/chroma/
5 files already formatted

Re-running the scan over src/diffusers/pipelines/chroma after the change reports 0 mismatches.

git diff --stat: 3 files, +7/-7.

Self-review (per CONTRIBUTING)

Ran the .ai/skills/self-review rubric against .ai/review-rules.md:

  • Blocking issues: none. Docstring text only; no logic, signatures, or defaults changed.
  • # Copied from: all three __call__ methods checked individually — none carries a
    # Copied from header (the markers in these files sit on helpers like encode_prompt and
    _pack_latents), so editing the three docstrings directly is correct rather than fixing an upstream
    source and running make fix-copies. utils/check_copies.py is outside my sparse checkout, so this
    is the manual equivalent; CI's consistency check will confirm.
  • Ephemeral context: none added.
  • Documentation impact: this is the documentation fix; no docs/ page repeats these numbers
    (checked docs/source/en/api/pipelines/chroma.md).
  • Dead code analysis: not applicable.

Not claimed

The same scan finds ~190 more defaults to mismatches elsewhere in src/diffusers/, heavily
clustered in other pipeline families (num_inference_steps 50 → 28 in 13 files,
guidance_scale 7.5 → 5.0 in 12, and so on). I kept this PR to one pipeline family rather than
sending a repo-wide sweep. If you'd like the rest, tell me whether you prefer them per-family or as
one batch and I'll follow up — and if you'd rather this were enforced mechanically instead, that scan
could become a utils/ check.


🤖 Written with Claude Code. All seven signature defaults were read
programmatically and the correct-already entries were verified rather than assumed.

iridescentWen and others added 2 commits August 20, 2026 16:13
Prose, comments and docstrings only. No executable line changed.

docs/:
- optimization/memory.md: maxmium -> maximum; heigh -> height (in the
  channels_last layout tuple, which read "(batch size, heigh, width,
  channels)")
- api/pipelines/bria_fibo.md: proffesional -> professional
- api/pipelines/wan.md: involed -> involved

src/ comments and docstrings:
- guiders/magnitude_aware_guidance.py: supression -> suppression
- models/attention.py: spliting -> splitting
- models/attention_dispatch.py: abritrary -> arbitrary (x2)
- models/transformers/transformer_ltx2.py: timstamps -> timestamps (x2)
- pipelines/ltx2/pipeline_ltx2{,_image2video}.py: corrct -> correct
- pipelines/deprecated/unidiffuser/modeling_uvit.py: tbe -> the
- pipelines/visualcloze/pipeline_visualcloze_{combined,generation}.py:
  "whe they are lists" -> "when they are lists" in a user-facing
  ValueError message

Deliberately not touched:
- pipeline_kandinsky*.py "promt"/"scren" live inside prompt_template,
  which is fed to the text encoder verbatim. Changing them would change
  generation output.
- ANE (Apple Neural Engine), MoT (Mixture-of-Transformers): initialisms.
- "racoon": appears in prompt examples whose reference images were
  generated with that exact prompt.
- "Shuting Wang": a paper author's name.
Seven `defaults to X` entries in the three Chroma pipelines' __call__
docstrings name a value the signature does not use, so copying the
documented number reproduces different behavior than leaving the argument
out. Values taken from each __call__ signature.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@github-actions github-actions Bot added documentation Improvements or additions to documentation models pipelines guiders size/S PR with diff < 50 LOC labels Aug 24, 2026
@github-actions

Copy link
Copy Markdown
Contributor

Hi @iridescentWen, thanks for the PR! It does not appear to link an issue it fixes. If this PR addresses an existing issue, please add a closing keyword (e.g. Fixes #1234) to the PR description so the issue is linked. See the contribution guide for more details. If this PR intentionally does not fix a tracked issue, a maintainer can add the no-issue-needed label to silence this reminder.

Please note that PRs without a linked issue are likely to be automatically closed 10 days after this notice.

Once the PR links an issue (or gets the no-issue-needed label), you can ignore this message — it stays here as a comment, but it no longer applies.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation guiders models pipelines size/S PR with diff < 50 LOC

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant