Add I-DLM pipeline + scheduler (Introspective Diffusion Language Models)

Adds `IDLMPipeline` + `IDLMBlockDiffusionScheduler` implementing Introspective
Strided Decoding (Yu et al., 2026). Mirrors the SDAR/DFlash conventions: the
scheduler owns the pure-math accept/resample logic (min(1, p/(alpha*q)) with
max(0, p - alpha*q) resampling on reject) and per-round new-spec sampling; the
pipeline orchestrates the block-N ISD loop, cache management via DynamicCache,
and chat-template handling.

Each round is a single target-model forward over

    [pending, spec_0, ..., spec_{K-1}, MASK, ..., MASK]   # length 2*N - 1

under strict causal attention. Under I-DLM's Dream-style logit shift,
`logits[:, i, :]` predicts the token at input position `i+1`, so the same
forward both verifies the pending specs (against the anchor p at their now-
clean positions) and samples the next batch of specs from the MASK-position
anchors. On partial accept, the corrected token seeds a cold-start next round.

Also: as part of aligning with the standard transformers v5 cache convention
(use_cache=True + past_key_values always stores), switch `SDARPipeline` from
the dual `store_kv=True/False` kwarg to a `DynamicCache.crop(prev_seq_len)`
snapshot-and-rollback after read-only denoising forwards. Same behavior, no
custom model-side flag required.

- src/diffusers/pipelines/idlm/ (pipeline + package init)
- src/diffusers/schedulers/scheduling_idlm_block_diffusion.py
- tests/pipelines/idlm/test_idlm.py (7 unit tests)
- examples/discrete_diffusion/sample_idlm.py (inference)
- examples/discrete_diffusion/train_idlm.py (reference training loop)
- docs/source/en/api/{pipelines,schedulers}/idlm*.md + TOC entries
- src/diffusers/{__init__,pipelines/__init__,schedulers/__init__}.py registrations
- src/diffusers/pipelines/sdar/pipeline_sdar.py: crop-based retrieve-only

End-to-end verified with `yifanyu/I-DLM-8B` (loaded via `refs/pr/2`):
  prompt: "What is 2+2?" -> "2 + 2 equals 4."

Author: kashif

docs/source/en/_toctree.yml

@@ -560,6 +560,8 @@
         title: HunyuanImage2.1
       - local: api/pipelines/hybrid_token_diffusion
         title: Hybrid Token Diffusion
+      - local: api/pipelines/idlm
+        title: I-DLM
       - local: api/pipelines/pix2pix
         title: InstructPix2Pix
       - local: api/pipelines/kandinsky
@@ -749,6 +751,8 @@
       title: HeunDiscreteScheduler
     - local: api/schedulers/hybrid_token_diffusion
       title: HybridTokenDiffusionScheduler
+    - local: api/schedulers/idlm_block_diffusion
+      title: IDLMBlockDiffusionScheduler
     - local: api/schedulers/ipndm
       title: IPNDMScheduler
     - local: api/schedulers/stochastic_karras_ve

docs/source/en/api/pipelines/idlm.md

@@ -0,0 +1,39 @@
+<!--Copyright 2025 The HuggingFace Team. All rights reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
+an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.
+-->
+
+# I-DLM
+
+[Introspective Diffusion Language Models (I-DLM)](https://arxiv.org/abs/2604.11035) are diffusion LLMs that recover the AR self-consistency property (the "introspective acceptance rate" of ~0.98) via strict causal attention, Dream-style logit shift, and all-masked training. At inference time, *Introspective Strided Decoding* (ISD) runs a single forward per round that both **verifies** previously-proposed speculative tokens (against the anchor distribution `p` at now-visible clean positions) and **generates** the next batch of specs (from the MASK-position proposal distribution `q`). Acceptance via `min(1, p(x) / (alpha * q(x)))` guarantees the output matches the base AR distribution.
+
+Published I-DLM checkpoints (e.g. [`yifanyu/I-DLM-8B`](https://huggingface.co/yifanyu/I-DLM-8B)) are finetuned from standard Qwen3 weights and load via `AutoModelForCausalLM.from_pretrained(..., trust_remote_code=True)`.
+
+```python
+import torch
+from transformers import AutoModelForCausalLM, AutoTokenizer
+from diffusers import IDLMPipeline, IDLMBlockDiffusionScheduler
+
+model = AutoModelForCausalLM.from_pretrained("yifanyu/I-DLM-8B", trust_remote_code=True, dtype=torch.bfloat16)
+tokenizer = AutoTokenizer.from_pretrained("yifanyu/I-DLM-8B", trust_remote_code=True)
+
+scheduler = IDLMBlockDiffusionScheduler(gen_block_size=4)
+pipe = IDLMPipeline(model=model, tokenizer=tokenizer, scheduler=scheduler)
+out = pipe(prompt="Prove that sqrt(2) is irrational.", max_new_tokens=256, use_chat_template=True)
+print(out.texts[0])
+```
+
+## IDLMPipeline
+[[autodoc]] IDLMPipeline
+    - all
+    - __call__
+
+## IDLMPipelineOutput
+[[autodoc]] pipelines.IDLMPipelineOutput

docs/source/en/api/schedulers/idlm_block_diffusion.md

@@ -0,0 +1,21 @@
+<!--Copyright 2025 The HuggingFace Team. All rights reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
+an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.
+-->
+
+# IDLMBlockDiffusionScheduler
+
+`IDLMBlockDiffusionScheduler` implements the block-N Introspective Strided Decoding step for I-DLM: speculative verification via `min(1, p/(alpha*q))` with `max(0, p - alpha*q)` resampling on reject, plus sampling of the next batch of speculative tokens from the MASK-position anchor logits. It is stateless and pure-math — the pipeline owns model and cache I/O.
+
+## IDLMBlockDiffusionScheduler
+[[autodoc]] IDLMBlockDiffusionScheduler
+
+## IDLMBlockDiffusionSchedulerOutput
+[[autodoc]] schedulers.scheduling_idlm_block_diffusion.IDLMBlockDiffusionSchedulerOutput

examples/discrete_diffusion/sample_idlm.py

@@ -0,0 +1,140 @@
+#!/usr/bin/env python
+# Copyright 2025 The HuggingFace Team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+Sample script for I-DLM (Introspective Diffusion Language Model) block-N decoding.
+
+Example:
+    python sample_idlm.py \
+      --model_id yifanyu/I-DLM-8B \
+      --prompt "Prove that sqrt(2) is irrational." \
+      --gen_block_size 4 \
+      --max_new_tokens 256
+"""
+
+import argparse
+
+import torch
+from transformers import AutoModelForCausalLM, AutoTokenizer
+
+from diffusers import IDLMBlockDiffusionScheduler, IDLMPipeline
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Run I-DLM introspective strided decoding.")
+    parser.add_argument("--model_id", type=str, default="yifanyu/I-DLM-8B", help="Model ID or local path.")
+    parser.add_argument(
+        "--prompt",
+        type=str,
+        default="Prove that sqrt(2) is irrational.",
+        help="Prompt text to generate from.",
+    )
+    parser.add_argument("--max_new_tokens", type=int, default=256)
+    parser.add_argument(
+        "--gen_block_size",
+        type=int,
+        default=4,
+        help="Block size N: each ISD round commits up to N tokens. `block_size = 2*N - 1`.",
+    )
+    parser.add_argument("--temperature", type=float, default=1.0)
+    parser.add_argument("--top_k", type=int, default=50)
+    parser.add_argument("--top_p", type=float, default=0.95)
+    parser.add_argument(
+        "--verify_alpha",
+        type=float,
+        default=1.0,
+        help="Leniency in the min(1, p/(alpha*q)) accept criterion. 1.0 = standard verify.",
+    )
+    parser.add_argument("--mask_token_id", type=int, default=None)
+    parser.add_argument("--use_chat_template", action="store_true")
+    parser.add_argument("--add_generation_prompt", action="store_true")
+    parser.add_argument(
+        "--enable_thinking",
+        action="store_true",
+        help="Enable <think>...</think> reasoning in the chat template. I-DLM is a Qwen3-derivative; "
+        "thinking is ON by default in the Qwen3 template. Pass this flag to keep it on.",
+    )
+    parser.add_argument(
+        "--device",
+        type=str,
+        default="cuda" if torch.cuda.is_available() else "cpu",
+    )
+    parser.add_argument(
+        "--dtype",
+        type=str,
+        default="auto",
+        choices=["auto", "float32", "float16", "bfloat16"],
+    )
+    parser.add_argument("--revision", type=str, default=None)
+    parser.add_argument("--seed", type=int, default=None)
+
+    args = parser.parse_args()
+
+    dtype_map = {"float32": torch.float32, "float16": torch.float16, "bfloat16": torch.bfloat16}
+    torch_dtype = dtype_map.get(args.dtype)
+
+    print(f"Loading model: {args.model_id}")
+    model = AutoModelForCausalLM.from_pretrained(
+        args.model_id,
+        trust_remote_code=True,
+        dtype=torch_dtype if torch_dtype is not None else "auto",
+        device_map=args.device,
+        revision=args.revision,
+    )
+    tokenizer = AutoTokenizer.from_pretrained(args.model_id, trust_remote_code=True, revision=args.revision)
+    if tokenizer.mask_token is None:
+        tokenizer.add_special_tokens({"mask_token": "<|MASK|>"})
+
+    scheduler = IDLMBlockDiffusionScheduler(
+        gen_block_size=args.gen_block_size,
+        temperature=args.temperature,
+        top_k=args.top_k,
+        top_p=args.top_p,
+        verify_alpha=args.verify_alpha,
+    )
+    pipe = IDLMPipeline(model=model, tokenizer=tokenizer, scheduler=scheduler)
+
+    generator = None
+    if args.seed is not None:
+        generator = torch.Generator(device=args.device).manual_seed(args.seed)
+
+    print(f"\nPrompt: {args.prompt}")
+    chat_template_kwargs = {"enable_thinking": bool(args.enable_thinking)}
+    output = pipe(
+        prompt=args.prompt,
+        max_new_tokens=args.max_new_tokens,
+        gen_block_size=args.gen_block_size,
+        temperature=args.temperature,
+        top_k=args.top_k,
+        top_p=args.top_p,
+        verify_alpha=args.verify_alpha,
+        mask_token_id=args.mask_token_id,
+        use_chat_template=args.use_chat_template,
+        add_generation_prompt=args.add_generation_prompt,
+        chat_template_kwargs=chat_template_kwargs,
+        generator=generator,
+    )
+
+    print("\nGenerated text:")
+    print(
+        output.texts[0]
+        if output.texts is not None
+        else tokenizer.decode(output.sequences[0], skip_special_tokens=True)
+    )
+    print(f"\nGenerated {output.sequences.shape[1]} tokens")
+
+
+if __name__ == "__main__":
+    main()