[Gronoxx]

What does this PR do?

This is my first contribution to the repo, so let me be upfront about the size of it. The diff is 29 return annotations and no runtime behavior. I read CONTRIBUTING, including the part about avoiding busywork PRs and the note that code agents tend to zero in on theoretical bugs found by static analysis. That is exactly why I am starting with the use case instead of the scan.

I hit this in my own work, worked around it, and finished what I was doing. I am opening the PR now because the next person who hits it will spend the same time I did figuring out what went wrong, and the signature will keep telling them they are right the whole way.

How I ran into it

I hit this in code that needs to iterate TransformerBlock objects by hand instead of calling model(...). Nothing about it is special to the failure. Anyone stepping through the blocks manually is in the same position.

My code came from 4.x. On v4.57.6, TransformerBlock.forward did literally this:

output = (ffn_output,)
if output_attentions:
    output = (sa_weights,) + output
return output

annotated -> tuple[torch.Tensor, ...]. The annotation was correct, and x = block(x, attn)[0] was the right way to write it. On 5.x the body is return ffn_output, a plain Tensor. The annotation did not change. The signature still endorses the [0].

Measured with the config from the reproducer below:

	shape
block input	(4, 5, 32)
block output (Tensor)	(4, 5, 32)
out[0]	(5, 32), 3 of the 4 samples gone

In my case the blocks were chained, so the next block received a rank 2 tensor where it expected rank 3 and raised IndexError. I got an exception rather than wrong numbers.

Anyone calling a single block without chaining, which is the normal shape of activation analysis, feature extraction and hooks, gets no exception at all. They get (5, 32) where they expected (4, 5, 32) and move on. torch.allclose(out[0], out) also passes, since (5, 32) broadcasts against (4, 5, 32), so a naive equality check does not catch it either.

What resolved it for me was reading the body of forward, not the signature.

Who this affects

It breaks people who iterate layers by hand: interpretability, pruning, early exit, distillation, activation analysis. Those are the people reading the signature on IDE hover, and the signature induces the [0].

It does not affect anyone using high level Model.forward, which is most users, since they never touch these classes.

The win for type checkers is honestly small. Measured with ty 0.0.75, the version make typing uses:

expression	without patch	with patch
blk(x, None) via __call__	Unknown	Unknown
blk.forward(x, None)	tuple[Tensor, ...]	Tensor

PyTorch types nn.Module.__call__ as Any, so the annotation only becomes visible on a direct forward call. Practical for people manipulating layers, theoretical for everyone else.

This is not a one off

Comparing each class against v4.57.6:

situation on v4.57.6	count of 29
returned a tuple and the tuple[...] annotation was correct, forward changed in 5.x and the annotation stayed behind	10
returned a tuple but the annotation said torch.Tensor, the two swapped sides in 5.x	5
already returned a Tensor with a tuple[...] annotation, already wrong back then	8
model did not exist on v4.57.6	6

The first row is the one that hurts: AlbertLayerGroup, DbrxFFN, DbrxRouter, DiaEncoderLayer, Gemma2DecoderLayer, GitAttention, GitLayer, TransformerBlock, ZambaMambaDecoderLayer, Zamba2MambaDecoderLayer. Anyone who wrote [0] on 4.x, which was correct, and then migrated, still has a signature backing that [0].

The five SparseMoeBlock classes (Mixtral, MiniMax, Qwen2-MoE, Qwen3-Next, Qwen3-Omni-Talker) are the inverted case. On 4.x they returned (final_hidden_states, router_logits) annotated torch.Tensor. Today they return the tensor annotated tuple[torch.Tensor, torch.Tensor]. The two just swapped places.

What changed

29 classes, 36 files, 40 lines. Every edited line has the same shape:

-    ) -> tuple[torch.FloatTensor, tuple[torch.FloatTensor, torch.FloatTensor] | None]:
+    ) -> torch.Tensor:

11 annotations were edited in modular_*.py, the rest directly in modeling_*.py for models without a modular file. Generated files came out of utils/modular_model_converter.py. Several models changed by inheritance alone, for example MiniMaxSparseMoeBlock(MixtralSparseMoeBlock) and Qwen3_5MoeSparseMoeBlock(Qwen3NextSparseMoeBlock(Qwen2MoeSparseMoeBlock)). Annotations only, no runtime behavior changes.

How the list was built

An AST scan over every modeling_*.py found 1734 forward methods annotated tuple[...], of which 76 return a single name that never receives a tuple construction anywhere in the function. Each of the 76 was instantiated and called with a minimal config, and the return type observed.

Two were refuted that way, Data2VecVisionSelfAttention and FlavaSelfAttention, which do return tuples. They are out. The 29 in this PR were all confirmed at runtime against the patched code.

One more that the verification killed: RecurrentGemmaRecurrentBlock returns a Tensor on 5.9.0, but on main the body is return (hidden_states, None). The annotation is correct today. It was on my list and I removed it.

Checks

command	result
utils/check_modular_conversion.py	passes
utils/check_copies.py	passes
ruff check (0.14.10, the version pinned in setup.py)	clean
ruff format --check	36 files already formatted
utils/checkers.py --fix (modular_conversion, copies, ruff_check, ruff_format, types, modeling_structure, imports, init_isort, inits, repo)	all pass, 0 files modified

I ran the make fix-repo checkers that touch this patch with --fix and none of them wanted to change anything. The full make fix-repo does not run on this machine, since some checkers need the complete pip install -e '.[dev]'.

Tests

CONTRIBUTING asks to run the tests covering the changed files. utils/tests_fetcher.py expanded to around 500 files, since the diff touches modular files of base models that many others inherit from. So I ran the full suite for the 27 directly touched models twice, once on the branch and once on clean main.

27 of 27 identical, same passed, failed and error counts on both sides. 4,267 tests executed (8,585 collected) and 46,029 subtests.

One caveat worth declaring: a few failures show up on both sides because accelerate is not installed on this machine, and installing it drags in a conflicting torch. Those are test_can_load_with_device_context_manager, test_can_load_with_global_device_set, test_causal_lm_can_accept_training_kwargs, test_generate_with_static_cache and test_generate_from_inputs_embeds_with_static_cache.

Related work

The same defect was confirmed by a maintainer in issue #45208 and fixed for Qwen3MoeSparseMoeBlock in PR #45352, which is merged.

Open PR #43446, [typings] Automatically type decorator return types as tuple | X, addresses the same family from another angle, on methods decorated with can_return_tuple. It touches 12 of the same files but none of the 29 classes here, so the two are complementary.

One adjacent finding I did not include: Cohere2MoeTopKRouter has the inverse problem, annotated -> torch.Tensor while returning (router_logits, router_scores, selected_experts). Happy to send that separately if you want it.

Minimal reproducer

import torch, inspect
from transformers import DistilBertConfig
from transformers.models.distilbert.modeling_distilbert import TransformerBlock

blk = TransformerBlock(DistilBertConfig(dim=32, n_heads=4, hidden_dim=64, n_layers=1)).eval()
out = blk(torch.randn(4, 5, 32), None)

print(inspect.signature(TransformerBlock.forward).return_annotation)  # tuple[torch.Tensor, ...]
print(type(out))                                                      # <class 'torch.Tensor'>
print(out.shape, out[0].shape)          # torch.Size([4, 5, 32]) torch.Size([5, 32])

Code Agent Policy

The Transformers repo is currently being overwhelmed by a large number of PRs and issue comments written by
code agents. These often are low-quality, or fix extremely minor issues that occur rarely or never in practice.
As a result, we're instituting a rule that first-time contributors should not use code agents to submit PRs or issues.
We'd also ask autonomous "OpenClaw"-like agents not to open any PRs or issues.

Issues/PRs from first-time contributors that violate this rule will probably just be closed without review, and we
might block you, especially if you open more than one or appear to be deliberately ignoring this. We especially do not
want new contributors to jump in on random issues to contribute an agent-written fix. This creates lots of noise
for reviewers and other users and will almost certainly get you blocked.

For more information, please read CONTRIBUTING.md.

• (First-time contributors only): I confirm that this PR description and code is not written by an LLM or code agent

Before submitting

• This PR fixes a typo or improves the docs (you can dismiss the other checks if that's the case).
• Did you read the contributor guideline and the
  Pull Request checks?
• 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 according to the guidelines?
• Did you write any new necessary tests?

Three of these are unchecked on purpose. There is no issue covering this, so the closest thing to prior approval is the maintainer confirmation in #45208 and the merged #45352, both cited above. No docstrings changed, so there is nothing to document. I did not write new tests, since the change is annotation only, but I ran the existing suite for all 27 touched models on both sides and got identical results.

Who can review?

@Rocketknight1, since you reviewed and merged #45352, which is the same defect on one class.

Happy to adjust anything.
:)

[github-actions]

[For maintainers] Suggested jobs to run (before merge)

run-slow: albert, canine, cohere, cohere2, cohere2_moe, cohere_compass, dbrx, dia, distilbert, gemma2, git, gpt_bigcode, internvl, minimax, minimax_m2, mixtral

[github-actions]

---

CI recap

Dashboard: View test results in Grafana
Latest run: 33036472075
Result: success | Grafana metrics are not available yet.

[Rocketknight1]

Yes, this is a good type hint fix, and I appreciate you making the same fix everywhere in a single PR!

[HuggingFaceDocBuilderDev]

The docs for this PR live here. All of your documentation changes will be reflected on that endpoint. The docs are available until 30 days after the last update.