From a46db134dbe8ee1d103c7bb3e37ae69ef17834c6 Mon Sep 17 00:00:00 2001 From: yiyixuxu Date: Thu, 30 Jul 2026 18:44:07 +0000 Subject: [PATCH 1/9] Auto-reply to new model requests with Modular Diffusers guidance Points new model/pipeline/scheduler requests at building a Hub-hosted modular pipeline instead of waiting on a core PR, and asks requesters to tag @asomoza when they have something to share. Gates on the `### Model/Pipeline/Scheduler description` heading the issue form renders rather than on a label: the label the template declares does not exist in this repo, so GitHub never applies it, and template labels land after issue creation anyway. Co-Authored-By: Claude Opus 5 (1M context) --- .github/workflows/new_model_request_reply.yml | 53 +++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 .github/workflows/new_model_request_reply.yml diff --git a/.github/workflows/new_model_request_reply.yml b/.github/workflows/new_model_request_reply.yml new file mode 100644 index 000000000000..9e7a32149257 --- /dev/null +++ b/.github/workflows/new_model_request_reply.yml @@ -0,0 +1,53 @@ +name: New Model Request Reply + +on: + issues: + types: [opened] + +jobs: + reply: + name: Point new model requests at Modular Diffusers + # Match the heading the issue form renders for its first field rather than a label: template + # labels are applied after the issue is created, so `github.event.issue.labels` is empty here. + # Keep this string in sync with .github/ISSUE_TEMPLATE/new-model-addition.yml. + if: >- + github.repository == 'huggingface/diffusers' && + contains(github.event.issue.body, '### Model/Pipeline/Scheduler description') + runs-on: ubuntu-latest + permissions: + issues: write + steps: + - name: Post Modular Diffusers guidance + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + GH_REPO: ${{ github.repository }} + ISSUE_NUMBER: ${{ github.event.issue.number }} + # `@asomoza` is in backticks on purpose: GitHub does not notify for mentions inside a + # code span, so the reply says who to tag without pinging him on every request. + BODY: | + Thanks for the request! + + **How new model support works in Diffusers** + + We're a small team and can only integrate and maintain so many models ourselves. We don't want our review process to be the bottleneck. + + So we've been building a system to support a more decentralized way of building with Diffusers: with [Modular Diffusers](https://huggingface.co/docs/diffusers/modular_diffusers/overview), pipelines can be hosted in any Hub repo and loaded straight from there with `from_pretrained`. + + ๐Ÿ› ๏ธ **Want to bring this model to Diffusers?** + + You don't have to send a PR. Build it as a modular pipeline under your own Hub repo and share it in this thread โ€” tag `@asomoza` and we'll give feedback on the implementation, help get it in front of people, and add the ones we like to our hand-picked [Modular Diffusers Custom Blocks](https://huggingface.co/collections/diffusers/modular-diffusers-custom-blocks) collection. The pipelines we integrate into `diffusers` are usually the ones people are already using. + + And one of the most valuable contributions you can make is helping us improve the experience of building on it โ€” so tell us about the friction as you go: confusing APIs, missing docs, bugs. + + ๐Ÿ‘‹ **Are you an author of the model?** + + We'd love to hear from you โ€” comment here or reach out and we'll talk through the options. Depending on the model and what you're aiming for, that might be a Hub-hosted modular pipeline (fastest, fully under your control, you own the release timeline) or a PR into the library. Happy to help you figure out which one fits. + + ๐Ÿ“š **Resources** + + - [Modular Diffusers quickstart](https://huggingface.co/docs/diffusers/modular_diffusers/quickstart) โ€” start here + - [Building custom blocks](https://huggingface.co/docs/diffusers/modular_diffusers/custom_blocks) โ€” template repo, and how to publish to the Hub + - [Custom blocks collection](https://huggingface.co/collections/diffusers/modular-diffusers-custom-blocks) โ€” examples to crib from + + *This is an automated message.* + run: gh issue comment "$ISSUE_NUMBER" --body "$BODY" From a6a9f7c347c5452565de79b1dc48354abc8f63b5 Mon Sep 17 00:00:00 2001 From: YiYi Xu Date: Thu, 30 Jul 2026 08:51:44 -1000 Subject: [PATCH 2/9] Apply suggestion from @yiyixuxu --- .github/workflows/new_model_request_reply.yml | 2 -- 1 file changed, 2 deletions(-) diff --git a/.github/workflows/new_model_request_reply.yml b/.github/workflows/new_model_request_reply.yml index 9e7a32149257..9c13e1748a7d 100644 --- a/.github/workflows/new_model_request_reply.yml +++ b/.github/workflows/new_model_request_reply.yml @@ -22,8 +22,6 @@ jobs: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} GH_REPO: ${{ github.repository }} ISSUE_NUMBER: ${{ github.event.issue.number }} - # `@asomoza` is in backticks on purpose: GitHub does not notify for mentions inside a - # code span, so the reply says who to tag without pinging him on every request. BODY: | Thanks for the request! From 647f918c425bc07ba9eb2c2e47116ff4d15129bd Mon Sep 17 00:00:00 2001 From: yiyixuxu Date: Thu, 30 Jul 2026 19:07:23 +0000 Subject: [PATCH 3/9] Tighten the new model request reply Lead with starting on the Hub and frame what follows as a support decision (work with the authors, upstream a community version, or point people at the Hub one) rather than a soft no to PRs. Trims the message by collapsing the author section and the resource list. Co-Authored-By: Claude Opus 5 (1M context) --- .github/workflows/new_model_request_reply.yml | 18 +++++------------- 1 file changed, 5 insertions(+), 13 deletions(-) diff --git a/.github/workflows/new_model_request_reply.yml b/.github/workflows/new_model_request_reply.yml index 9c13e1748a7d..4e21b2927780 100644 --- a/.github/workflows/new_model_request_reply.yml +++ b/.github/workflows/new_model_request_reply.yml @@ -27,25 +27,17 @@ jobs: **How new model support works in Diffusers** - We're a small team and can only integrate and maintain so many models ourselves. We don't want our review process to be the bottleneck. - - So we've been building a system to support a more decentralized way of building with Diffusers: with [Modular Diffusers](https://huggingface.co/docs/diffusers/modular_diffusers/overview), pipelines can be hosted in any Hub repo and loaded straight from there with `from_pretrained`. + We're a small team, and our review queue shouldn't be what decides whether a model is usable in Diffusers. With [Modular Diffusers](https://huggingface.co/docs/diffusers/modular_diffusers/overview) it doesn't have to be: a pipeline can live as remote code in any Hub repo and load straight from there with `from_pretrained`. ๐Ÿ› ๏ธ **Want to bring this model to Diffusers?** - You don't have to send a PR. Build it as a modular pipeline under your own Hub repo and share it in this thread โ€” tag `@asomoza` and we'll give feedback on the implementation, help get it in front of people, and add the ones we like to our hand-picked [Modular Diffusers Custom Blocks](https://huggingface.co/collections/diffusers/modular-diffusers-custom-blocks) collection. The pipelines we integrate into `diffusers` are usually the ones people are already using. - - And one of the most valuable contributions you can make is helping us improve the experience of building on it โ€” so tell us about the friction as you go: confusing APIs, missing docs, bugs. - - ๐Ÿ‘‹ **Are you an author of the model?** + Please start with a Hub repo โ€” you don't need anything from us to do that, and people can use it immediately. From there we decide how to support it: we might work with the authors, upstream an existing community version, or just point people at the one on the Hub. The pipelines we integrate are usually the ones people are already running. - We'd love to hear from you โ€” comment here or reach out and we'll talk through the options. Depending on the model and what you're aiming for, that might be a Hub-hosted modular pipeline (fastest, fully under your control, you own the release timeline) or a PR into the library. Happy to help you figure out which one fits. + Tag `@asomoza` when you have something to share โ€” we'll give feedback on the implementation, help get it in front of people, and add the ones we like to our hand-picked [Custom Blocks](https://huggingface.co/collections/diffusers/modular-diffusers-custom-blocks) collection. Tell us where you hit friction along the way, too: confusing APIs, missing docs, bugs. That feedback is worth as much to us as the pipeline. - ๐Ÿ“š **Resources** + ๐Ÿ‘‹ **Are you an author of the model?** We'd love to hear from you โ€” comment here and we'll help you pick the path that fits. - - [Modular Diffusers quickstart](https://huggingface.co/docs/diffusers/modular_diffusers/quickstart) โ€” start here - - [Building custom blocks](https://huggingface.co/docs/diffusers/modular_diffusers/custom_blocks) โ€” template repo, and how to publish to the Hub - - [Custom blocks collection](https://huggingface.co/collections/diffusers/modular-diffusers-custom-blocks) โ€” examples to crib from + ๐Ÿ“š [Quickstart](https://huggingface.co/docs/diffusers/modular_diffusers/quickstart) ยท [Building custom blocks](https://huggingface.co/docs/diffusers/modular_diffusers/custom_blocks) โ€” template repo, and how to publish to the Hub *This is an automated message.* run: gh issue comment "$ISSUE_NUMBER" --body "$BODY" From 8062541b7c243ea3c7f23186d22c78bbb0178519 Mon Sep 17 00:00:00 2001 From: yiyixuxu Date: Thu, 30 Jul 2026 19:27:58 +0000 Subject: [PATCH 4/9] Link the Modular Pipelines collection in the reply Community-built model pipelines belong in the Modular Pipelines collection rather than Custom Blocks, so point the "we'll add the ones we like" line there and keep both collections in the resource list. Co-Authored-By: Claude Opus 5 (1M context) --- .github/workflows/new_model_request_reply.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/new_model_request_reply.yml b/.github/workflows/new_model_request_reply.yml index 4e21b2927780..3c74cc06f837 100644 --- a/.github/workflows/new_model_request_reply.yml +++ b/.github/workflows/new_model_request_reply.yml @@ -33,11 +33,11 @@ jobs: Please start with a Hub repo โ€” you don't need anything from us to do that, and people can use it immediately. From there we decide how to support it: we might work with the authors, upstream an existing community version, or just point people at the one on the Hub. The pipelines we integrate are usually the ones people are already running. - Tag `@asomoza` when you have something to share โ€” we'll give feedback on the implementation, help get it in front of people, and add the ones we like to our hand-picked [Custom Blocks](https://huggingface.co/collections/diffusers/modular-diffusers-custom-blocks) collection. Tell us where you hit friction along the way, too: confusing APIs, missing docs, bugs. That feedback is worth as much to us as the pipeline. + Tag `@asomoza` when you have something to share โ€” we'll give feedback on the implementation, help get it in front of people, and add the ones we like to our hand-picked [Modular Pipelines](https://huggingface.co/collections/diffusers/modular-pipelines) collection. Tell us where you hit friction along the way, too: confusing APIs, missing docs, bugs. That feedback is worth as much to us as the pipeline. ๐Ÿ‘‹ **Are you an author of the model?** We'd love to hear from you โ€” comment here and we'll help you pick the path that fits. - ๐Ÿ“š [Quickstart](https://huggingface.co/docs/diffusers/modular_diffusers/quickstart) ยท [Building custom blocks](https://huggingface.co/docs/diffusers/modular_diffusers/custom_blocks) โ€” template repo, and how to publish to the Hub + ๐Ÿ“š [Quickstart](https://huggingface.co/docs/diffusers/modular_diffusers/quickstart) ยท [Building custom blocks](https://huggingface.co/docs/diffusers/modular_diffusers/custom_blocks) โ€” template repo, and how to publish to the Hub ยท [Modular Pipelines](https://huggingface.co/collections/diffusers/modular-pipelines) and [Custom Blocks](https://huggingface.co/collections/diffusers/modular-diffusers-custom-blocks) โ€” examples to crib from *This is an automated message.* run: gh issue comment "$ISSUE_NUMBER" --body "$BODY" From c8d40458b1e8efb6e01107fd4093c945cf3aa2c7 Mon Sep 17 00:00:00 2001 From: yiyixuxu Date: Thu, 30 Jul 2026 19:27:58 +0000 Subject: [PATCH 5/9] Recommend starting on the Hub for new models Adds a callout to the contribution guide asking model authors to get in touch on a feature request, and community contributors to coordinate there and start with a Hub repo at the same time. Points agents the same way: default to publishing a modular pipeline as remote code rather than opening a PR against src/diffusers. Co-Authored-By: Claude Opus 5 (1M context) --- .ai/AGENTS.md | 6 ++++++ .ai/skills/model-integration/SKILL.md | 2 ++ docs/source/en/conceptual/contribution.md | 5 +++++ 3 files changed, 13 insertions(+) diff --git a/.ai/AGENTS.md b/.ai/AGENTS.md index ae611feb4bb6..9b3116ff494d 100644 --- a/.ai/AGENTS.md +++ b/.ai/AGENTS.md @@ -25,6 +25,12 @@ Strive to write code as simple and explicit as possible. - Do not edit a `# Copied from` block directly โ€” run `make fix-copies` to propagate changes from the source - Remove the header to intentionally break the link +## Adding a new model or pipeline + +Default to a Hub repo, not a PR into `src/diffusers`. A modular pipeline can be published as remote code in any Hub repo and loaded with `ModularPipeline.from_pretrained("", trust_remote_code=True)` โ€” it ships immediately instead of waiting on maintainer review, and the author keeps control of it. When someone asks to add a new model, offer that path first and use the [custom-blocks](./skills/custom-blocks/SKILL.md) skill. + +Adding to the library itself is the exception โ€” usually model authors, or a model people are already running โ€” and the scope should be agreed with maintainers on an issue before any PR. Use the [model-integration](./skills/model-integration/SKILL.md) skill for that path. + ## Reference guides - **Models** โ€” see [models.md](models.md) for model conventions, attention pattern, implementation rules, dependencies, and gotchas. For adding or converting a model, use the [model-integration](./skills/model-integration/SKILL.md) skill. diff --git a/.ai/skills/model-integration/SKILL.md b/.ai/skills/model-integration/SKILL.md index 856549085899..ca6c984f1c88 100644 --- a/.ai/skills/model-integration/SKILL.md +++ b/.ai/skills/model-integration/SKILL.md @@ -12,6 +12,8 @@ Integrate a new model into diffusers end-to-end, to full numerical parity with t ## Setup โ€” gather before starting +**First, check where this should live.** Default to a Hub repo, not `src/diffusers`: a modular pipeline can be published as remote code and loaded with `ModularPipeline.from_pretrained("", trust_remote_code=True)`, so it ships immediately instead of waiting on maintainer review. Use the [custom-blocks](../custom-blocks/SKILL.md) skill for that path. Continue with this skill when the target really is the library โ€” model authors, or a model people are already running โ€” with the scope agreed with maintainers on an issue first. + Before writing any code, gather info in this order: 1. **Reference repo** โ€” ask for the github link. If they've already set it up locally, ask for the path. Otherwise, ask what setup steps are needed (install deps, download checkpoints, set env vars, etc.) and run through them before proceeding. diff --git a/docs/source/en/conceptual/contribution.md b/docs/source/en/conceptual/contribution.md index 1e60515430b0..c088dbf1c74e 100644 --- a/docs/source/en/conceptual/contribution.md +++ b/docs/source/en/conceptual/contribution.md @@ -332,6 +332,11 @@ Good second issues are usually more difficult to get merged compared to good fir ### 9. Adding pipelines, models, schedulers +> [!TIP] +> If you are the model's author, please get in touch so we can coordinate the integration with you: open a feature request, or drop a comment if one is already open. +> +> If you are a community contributor, please also let us know you're interested under the feature request, and start with a Hub repo at the same time. See the [Modular Diffusers](../modular_diffusers/overview) guide to get started, and [custom blocks](../modular_diffusers/custom_blocks) for publishing a pipeline as remote code on the Hub. + Pipelines, models, and schedulers are the most important pieces of the Diffusers library. They provide easy access to state-of-the-art diffusion technologies and thus allow the community to build powerful generative AI applications. From fbe02f1512a730efcafb717e7e1b51658d01fbf0 Mon Sep 17 00:00:00 2001 From: YiYi Xu Date: Thu, 30 Jul 2026 09:29:12 -1000 Subject: [PATCH 6/9] Apply suggestion from @yiyixuxu --- .ai/skills/model-integration/SKILL.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/.ai/skills/model-integration/SKILL.md b/.ai/skills/model-integration/SKILL.md index ca6c984f1c88..856549085899 100644 --- a/.ai/skills/model-integration/SKILL.md +++ b/.ai/skills/model-integration/SKILL.md @@ -12,8 +12,6 @@ Integrate a new model into diffusers end-to-end, to full numerical parity with t ## Setup โ€” gather before starting -**First, check where this should live.** Default to a Hub repo, not `src/diffusers`: a modular pipeline can be published as remote code and loaded with `ModularPipeline.from_pretrained("", trust_remote_code=True)`, so it ships immediately instead of waiting on maintainer review. Use the [custom-blocks](../custom-blocks/SKILL.md) skill for that path. Continue with this skill when the target really is the library โ€” model authors, or a model people are already running โ€” with the scope agreed with maintainers on an issue first. - Before writing any code, gather info in this order: 1. **Reference repo** โ€” ask for the github link. If they've already set it up locally, ask for the path. Otherwise, ask what setup steps are needed (install deps, download checkpoints, set env vars, etc.) and run through them before proceeding. From 40e46f5724a2fb75d68f5947beac2ebdc811d598 Mon Sep 17 00:00:00 2001 From: YiYi Xu Date: Thu, 30 Jul 2026 09:29:59 -1000 Subject: [PATCH 7/9] Apply suggestion from @yiyixuxu --- .ai/AGENTS.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/.ai/AGENTS.md b/.ai/AGENTS.md index 9b3116ff494d..ae611feb4bb6 100644 --- a/.ai/AGENTS.md +++ b/.ai/AGENTS.md @@ -25,12 +25,6 @@ Strive to write code as simple and explicit as possible. - Do not edit a `# Copied from` block directly โ€” run `make fix-copies` to propagate changes from the source - Remove the header to intentionally break the link -## Adding a new model or pipeline - -Default to a Hub repo, not a PR into `src/diffusers`. A modular pipeline can be published as remote code in any Hub repo and loaded with `ModularPipeline.from_pretrained("", trust_remote_code=True)` โ€” it ships immediately instead of waiting on maintainer review, and the author keeps control of it. When someone asks to add a new model, offer that path first and use the [custom-blocks](./skills/custom-blocks/SKILL.md) skill. - -Adding to the library itself is the exception โ€” usually model authors, or a model people are already running โ€” and the scope should be agreed with maintainers on an issue before any PR. Use the [model-integration](./skills/model-integration/SKILL.md) skill for that path. - ## Reference guides - **Models** โ€” see [models.md](models.md) for model conventions, attention pattern, implementation rules, dependencies, and gotchas. For adding or converting a model, use the [model-integration](./skills/model-integration/SKILL.md) skill. From b81841457ec48fbb3bf943fb7d8a467320811e59 Mon Sep 17 00:00:00 2001 From: YiYi Xu Date: Thu, 30 Jul 2026 10:36:45 -1000 Subject: [PATCH 8/9] Update .github/workflows/new_model_request_reply.yml Co-authored-by: Steven Liu <59462357+stevhliu@users.noreply.github.com> --- .github/workflows/new_model_request_reply.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/new_model_request_reply.yml b/.github/workflows/new_model_request_reply.yml index 3c74cc06f837..f0c9e4c571af 100644 --- a/.github/workflows/new_model_request_reply.yml +++ b/.github/workflows/new_model_request_reply.yml @@ -27,7 +27,7 @@ jobs: **How new model support works in Diffusers** - We're a small team, and our review queue shouldn't be what decides whether a model is usable in Diffusers. With [Modular Diffusers](https://huggingface.co/docs/diffusers/modular_diffusers/overview) it doesn't have to be: a pipeline can live as remote code in any Hub repo and load straight from there with `from_pretrained`. + We're a small team, and our review queue shouldn't be what decides whether a model is usable in Diffusers. With [Modular Diffusers](https://huggingface.co/docs/diffusers/modular_diffusers/overview), a pipeline can live as remote code in any Hub repo and load straight from there with `from_pretrained`. ๐Ÿ› ๏ธ **Want to bring this model to Diffusers?** From 12b55adc6c0249d8980ed3d725d7ac135a89eca1 Mon Sep 17 00:00:00 2001 From: yiyixuxu Date: Fri, 31 Jul 2026 05:54:49 +0000 Subject: [PATCH 9/9] Consolidate the Hub-first guidance into one place MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit stevhliu noted the new callout in "Adding pipelines, models, schedulers" overlapped the last two paragraphs of the AI-assisted contributions section. Drop the community-contributor paragraph there โ€” it is general contribution policy rather than agent-specific guidance โ€” and point the model-author paragraph at the callout instead. Carry the custom models link over so the non-modular Hub path stays covered. Co-Authored-By: Claude Opus 5 (1M context) --- docs/source/en/conceptual/contribution.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/source/en/conceptual/contribution.md b/docs/source/en/conceptual/contribution.md index c088dbf1c74e..2eb3275fa95a 100644 --- a/docs/source/en/conceptual/contribution.md +++ b/docs/source/en/conceptual/contribution.md @@ -335,7 +335,7 @@ Good second issues are usually more difficult to get merged compared to good fir > [!TIP] > If you are the model's author, please get in touch so we can coordinate the integration with you: open a feature request, or drop a comment if one is already open. > -> If you are a community contributor, please also let us know you're interested under the feature request, and start with a Hub repo at the same time. See the [Modular Diffusers](../modular_diffusers/overview) guide to get started, and [custom blocks](../modular_diffusers/custom_blocks) for publishing a pipeline as remote code on the Hub. +> If you are a community contributor, please also let us know you're interested under the feature request, and start with a Hub repo at the same time. See the [Modular Diffusers](../modular_diffusers/overview) guide to get started, and [custom blocks](../modular_diffusers/custom_blocks) or [custom models](../using-diffusers/automodel) for publishing as remote code on the Hub. Pipelines, models, and schedulers are the most important pieces of the Diffusers library. They provide easy access to state-of-the-art diffusion technologies and thus allow the community to @@ -610,6 +610,4 @@ AI-assisted contributions are welcome, but they must be coordinated, scoped, and - The **test commands you ran** and their results (paste relevant output, not just "tests pass"). - Your **self-review notes** (or a link to the PR comment containing them), as described above. -If you are a model author or part of a team that officially maintains a model, we encourage you to use agents for a new model integration. Follow the repository's [recommended setup](https://github.com/huggingface/diffusers/blob/main/.ai/AGENTS.md) and use the [`model-integration`](https://github.com/huggingface/diffusers/blob/main/.ai/skills/model-integration/SKILL.md) skill. Coordinate the scope with maintainers before opening a PR. - -If you are contributing a model to Diffusers for the first time as a community contributor, we generally recommend starting with a custom implementation that loads code from the Hub. This gives users access to the model while its integration into the core library is evaluated. See the [custom models](../using-diffusers/automodel) and [custom modular blocks](../modular_diffusers/custom_blocks) guides for supported patterns. +If you are a model author or part of a team that officially maintains a model, we encourage you to use agents for a new model integration. Follow the repository's [recommended setup](https://github.com/huggingface/diffusers/blob/main/.ai/AGENTS.md) and use the [`model-integration`](https://github.com/huggingface/diffusers/blob/main/.ai/skills/model-integration/SKILL.md) skill. Coordinate the scope with maintainers before opening a PR โ€” see [Adding pipelines, models, schedulers](#9-adding-pipelines-models-schedulers).