chore(mlinter): implement part of rule TRF003 by tarekziade · Pull Request #45720 · huggingface/transformers

tarekziade · 2026-04-30T12:39:47Z

What does this PR do?

Enables rule TRF003 and implement it on 10 models

HuggingFaceDocBuilderDev · 2026-04-30T12:50:24Z

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.

github-actions · 2026-04-30T12:55:58Z

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

run-slow: bloom, data2vec, deberta, deberta_v2, falcon, hubert, longformer, longt5, mbart, mt5, sew, sew_d, t5, umt5, unispeech, unispeech_sat

github-actions · 2026-04-30T13:08:46Z

View the CircleCI Test Summary for this PR:

https://huggingface.co/spaces/transformers-community/circle-ci-viz?pr=45720&sha=cdd535

zucchini-nlp · 2026-04-30T13:11:47Z

+    @can_return_tuple
    @auto_docstring
    def forward(


not really sure this is what we want to enforce with linter. For base models we prefer capture_outputs which covers "collecting intermediate_outputs + return in tuple/dict format"

Tho updating all models for @capture_outputs will be a long PR, and prob needs to be delegated to a smarter variant of code agents

the change was generated by an agent using the mlinter rule as:

https://github.com/huggingface/transformers-mlinter/blob/main/mlinter/rules.toml#L31-L48

and I restricted it to 10 models only to avoid a large PR.
do you see something in that rule we should tweak to make sure capture_outputs takes precedence?

yeah, this model for ex (BloomModel), should have capture_outputs. But as said, it prob needs human intervention at some point, because we have to add correct classes in cls._can_record_ouputs and change returns from some modules

so what is your recommandation? drop rule 13 altogether?

no, no, we defi need a rule for these decorators. Can we check with new models that they don't use explicitly output_xx and don't check old models yet?

I think for old models we need a separate PR updating all of them to use correct decorators

Also, I don't know if it is possible, but enforcing a better choice of decorator would be great. For ex, base models need to use capture_outputs while the task-head models needs a can_return_tuple

The bad choice will return incorrect last_hidden_states and was already reported once with qwen3-vl

Yea, it's pretty hard due to old legacy models. The pattern usually is

can_return_tuple + auto_docstring on a wrapper model, mostly the ForXXX ones

merge_with_config_defaults + capture_outputs + auto_docstring for the base models underlying

It's not trivial, just take a look at #43590 😅

vasqu

I only went through the list that would need another round. I just wanted to comment on those I think that are important / recent

Not sure whether it makes sense in this PR directly tbh. Wdyt @zucchini-nlp to get this in and progressively refactor those we still need? I think we should also deprecate a bunch of these models either way tbh 👀

vasqu · 2026-05-04T17:09:33Z

+# longt5, mbart, mt5, t5, umt5, wav2vec2, and xlnet; the remaining ones are tracked here.
+allowlist_models = [
+    "bark", "beit", "bit", "blip_2", "canine", "codegen", "cpmant", "ctrl", "cvt",
+    "dab_detr", "dac", "data2vec", "decision_transformer", "depth_anything", "depth_pro",


dac is bound to dia so would be nice to fix here

vasqu · 2026-05-04T17:09:56Z

+    "dinat", "donut", "dpr", "efficientnet", "encodec", "falcon_mamba",
+    "fastspeech2_conformer", "flaubert", "flava", "fnet", "focalnet", "fsmt", "funnel",
+    "glpn", "gpt_neo", "gpt_neox_japanese", "gptj", "granite_speech",
+    "granite_speech_plus", "grounding_dino", "hgnet_v2", "hiera",


granite speech plus is very recent so should be fixed

vasqu · 2026-05-04T17:10:11Z

+    "fastspeech2_conformer", "flaubert", "flava", "fnet", "focalnet", "fsmt", "funnel",
+    "glpn", "gpt_neo", "gpt_neox_japanese", "gptj", "granite_speech",
+    "granite_speech_plus", "grounding_dino", "hgnet_v2", "hiera",
+    "higgs_audio_v2_tokenizer", "hubert", "ibert", "imagegpt", "kyutai_speech_to_text",


higgs + kyutai

vasqu · 2026-05-04T17:10:55Z

+    "glpn", "gpt_neo", "gpt_neox_japanese", "gptj", "granite_speech",
+    "granite_speech_plus", "grounding_dino", "hgnet_v2", "hiera",
+    "higgs_audio_v2_tokenizer", "hubert", "ibert", "imagegpt", "kyutai_speech_to_text",
+    "led", "levit", "lilt", "llama4", "luke", "lxmert", "mamba", "mamba2",


llama4 ig, maybe the mamba models since they are base model references for other models

vasqu · 2026-05-04T17:11:03Z

+    "granite_speech_plus", "grounding_dino", "hgnet_v2", "hiera",
+    "higgs_audio_v2_tokenizer", "hubert", "ibert", "imagegpt", "kyutai_speech_to_text",
+    "led", "levit", "lilt", "llama4", "luke", "lxmert", "mamba", "mamba2",
+    "mask2former", "maskformer", "megatron_bert", "mgp_str", "mimi", "mm_grounding_dino",


mimi is important

vasqu · 2026-05-04T17:11:09Z

+    "higgs_audio_v2_tokenizer", "hubert", "ibert", "imagegpt", "kyutai_speech_to_text",
+    "led", "levit", "lilt", "llama4", "luke", "lxmert", "mamba", "mamba2",
+    "mask2former", "maskformer", "megatron_bert", "mgp_str", "mimi", "mm_grounding_dino",
+    "mobilenet_v1", "mobilenet_v2", "mobilevit", "mobilevitv2", "moshi", "mpnet", "mpt",


zucchini-nlp · 2026-05-04T18:53:39Z

Yes, we do need this rule for sure. My point is to not just update with can_return_tuple, and instead move further with correct decorators. We have a tendency when users copy-paste existing code, so I am quite reluctant to keep a "less desired" code pattern

I am really bad at prompting but i think a capable agent like claude-code can do well if prompted correctly. It is a waste of engineering resources for us to update everything by hand 😭

vasqu · 2026-05-04T18:57:05Z

I think this one is simple enough for now where can return tuple works well for most edge cases on the rule. I think the models you think about will need a deeper restructure either way, just to have the proper wrapper patterns - not sure how well claude would manage nowadays :D

vasqu · 2026-05-04T18:57:58Z

So the goal with this PR is to collect the low hanging fruits and then adapt progressively

chore(mlinter): implement part of rule 003

4f1069e

tarekziade requested review from vasqu and zucchini-nlp April 30, 2026 12:43

fix-repo

cdd535a

zucchini-nlp reviewed Apr 30, 2026

View reviewed changes

vasqu reviewed May 4, 2026

View reviewed changes

Uh oh!

Conversation

tarekziade commented Apr 30, 2026

What does this PR do?

Uh oh!

HuggingFaceDocBuilderDev commented Apr 30, 2026

Uh oh!

github-actions Bot commented Apr 30, 2026

Uh oh!

github-actions Bot commented Apr 30, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

zucchini-nlp Apr 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vasqu May 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vasqu left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

zucchini-nlp commented May 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vasqu commented May 4, 2026

Uh oh!

vasqu commented May 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

zucchini-nlp Apr 30, 2026 •

edited

Loading

vasqu May 4, 2026 •

edited

Loading

zucchini-nlp commented May 4, 2026 •

edited

Loading